chatterer 0.1.14__py3-none-any.whl → 0.1.17__py3-none-any.whl

chatterer/__init__.py

@@ -41,9 +41,7 @@ from .tools import (
     render_pdf_as_image,
 )
 from .utils import (
-    ArgumentSpec,
     Base64Image,
-    BaseArguments,
     CodeExecutionResult,
     FunctionSignature,
     get_default_repl_tool,
@@ -92,6 +90,4 @@ __all__ = [
     "extract_text_from_pdf",
     "open_pdf",
     "render_pdf_as_image",
-    "ArgumentSpec",
-    "BaseArguments",
 ]

chatterer/interactive.py

@@ -1,5 +1,5 @@
-import sys
-from typing import TYPE_CHECKING, Any, Callable, Iterable, Optional
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Optional, Type, TypeVar, cast, overload
 
 from langchain_core.messages import (
     AIMessage,
@@ -9,8 +9,11 @@ from langchain_core.messages import (
 )
 from langchain_core.runnables import RunnableConfig
 from pydantic import BaseModel, Field
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Prompt
 
-from .language_model import Chatterer
+from .language_model import Chatterer, LanguageModelInput
 from .utils.code_agent import (
     DEFAULT_CODE_GENERATION_PROMPT,
     DEFAULT_FUNCTION_REFERENCE_PREFIX_PROMPT,
@@ -25,6 +28,7 @@ if TYPE_CHECKING:
     # Import only for type hinting to avoid circular dependencies if necessary
     from langchain_experimental.tools.python.tool import PythonAstREPLTool
 
+T = TypeVar("T", bound=BaseModel)
 
 # --- Pydantic Models ---
 
@@ -94,9 +98,8 @@ class Think(BaseModel):
 
 # --- Interactive Shell Function ---
 
-
 def interactive_shell(
-    chatterer: Chatterer = Chatterer.openai(),  # Assuming Chatterer.openai() is correct
+    chatterer: Chatterer,
     system_instruction: BaseMessage | Iterable[BaseMessage] = ([
         SystemMessage(
             "You are an AI assistant capable of answering questions and executing Python code to help users solve tasks."
@@ -112,10 +115,6 @@ def interactive_shell(
     **kwargs: Any,
 ) -> None:
     try:
-        from rich.console import Console
-        from rich.panel import Panel
-        from rich.prompt import Prompt
-
         console = Console()
         # Style settings
         AI_STYLE = "bold bright_blue"
@@ -125,23 +124,28 @@ def interactive_shell(
     except ImportError:
         raise ImportError("Rich library not found. Please install it: pip install rich")
 
+    # --- Shell Initialization and Main Loop ---
+    if repl_tool is None:
+        repl_tool = get_default_repl_tool()
+
+    def set_locals(**kwargs: object) -> None:
+        """Set local variables for the REPL tool."""
+        if repl_tool.locals is None:  # pyright: ignore[reportUnknownMemberType]
+            repl_tool.locals = {}
+        for key, value in kwargs.items():
+            repl_tool.locals[key] = value  # pyright: ignore[reportUnknownMemberType]
+
     def respond(messages: list[BaseMessage]) -> str:
         response = ""
-        if "rich" not in sys.modules:
+        with console.status("[bold yellow]AI is thinking..."):
+            response_panel = Panel("", title="AI Response", style=AI_STYLE, border_style="blue")
+            current_content = ""
             for chunk in chatterer.generate_stream(messages=messages):
-                print(chunk, end="", flush=True)
-                response += chunk
-            print()
-        else:
-            with console.status("[bold yellow]AI is thinking..."):
-                response_panel = Panel("", title="AI Response", style=AI_STYLE, border_style="blue")
-                current_content = ""
-                for chunk in chatterer.generate_stream(messages=messages):
-                    current_content += chunk
-                    # Update renderable (might not display smoothly without Live)
-                    response_panel.renderable = current_content
-                response = current_content
-            console.print(Panel(response, title="AI Response", style=AI_STYLE))
+                current_content += chunk
+                # Update renderable (might not display smoothly without Live)
+                response_panel.renderable = current_content
+            response = current_content
+        console.print(Panel(response, title="AI Response", style=AI_STYLE))
         return response.strip()
 
     def complete_task(think_before_speak: ThinkBeforeSpeak) -> None:
@@ -159,15 +163,15 @@ def interactive_shell(
 
         while True:
             current_context = context + session_messages
-            is_tool_call_needed: IsToolCallNeeded = chatterer.generate_pydantic(
-                response_model=IsToolCallNeeded,
-                messages=augment_prompt_for_toolcall(
+            is_tool_call_needed: IsToolCallNeeded = chatterer(
+                augment_prompt_for_toolcall(
                     function_signatures=function_signatures,
                     messages=current_context,
                     prompt_for_code_invoke=prompt_for_code_invoke,
                     function_reference_prefix=function_reference_prefix,
                     function_reference_seperator=function_reference_seperator,
                 ),
+                IsToolCallNeeded,
                 config=config,
                 stop=stop,
                 **kwargs,
@@ -175,7 +179,8 @@ def interactive_shell(
 
             if is_tool_call_needed.is_tool_call_needed:
                 # --- Code Execution Path ---
-                code_execution: CodeExecutionResult = chatterer.invoke_code_execution(
+                set_locals(__context__=context, __session__=session_messages)
+                code_execution: CodeExecutionResult = chatterer.exec(
                     messages=current_context,
                     repl_tool=repl_tool,
                     prompt_for_code_invoke=prompt_for_code_invoke,
@@ -200,15 +205,15 @@ def interactive_shell(
 
                 # --- Review Code Execution ---
                 current_context_after_exec = context + session_messages
-                decision = chatterer.generate_pydantic(
-                    response_model=ReviewOnToolcall,
-                    messages=augment_prompt_for_toolcall(
+                decision = chatterer(
+                    augment_prompt_for_toolcall(
                         function_signatures=function_signatures,
                         messages=current_context_after_exec,
                         prompt_for_code_invoke=prompt_for_code_invoke,
                         function_reference_prefix=function_reference_prefix,
                         function_reference_seperator=function_reference_seperator,
                     ),
+                    ReviewOnToolcall,
                     config=config,
                     stop=stop,
                     **kwargs,
@@ -233,15 +238,15 @@ def interactive_shell(
             else:
                 # --- Thinking Path (No Code Needed) ---
                 current_context_before_think = context + session_messages
-                decision = chatterer.generate_pydantic(
-                    response_model=Think,  # Uses updated description
-                    messages=augment_prompt_for_toolcall(
+                decision = chatterer(
+                    augment_prompt_for_toolcall(
                         function_signatures=function_signatures,
                         messages=current_context_before_think,
                         prompt_for_code_invoke=prompt_for_code_invoke,
                         function_reference_prefix=function_reference_prefix,
                         function_reference_seperator=function_reference_seperator,
                     ),
+                    Think,
                     config=config,
                     stop=stop,
                     **kwargs,
@@ -277,10 +282,6 @@ def interactive_shell(
         # Add the final AI response to the main context
         context.append(AIMessage(content=response))
 
-    # --- Shell Initialization and Main Loop ---
-    if repl_tool is None:
-        repl_tool = get_default_repl_tool()
-
     if additional_callables:
         if callable(additional_callables):
             additional_callables = [additional_callables]
@@ -321,15 +322,15 @@ def interactive_shell(
 
         try:
             # Initial planning step
-            initial_plan_decision = chatterer.generate_pydantic(
-                response_model=ThinkBeforeSpeak,
-                messages=augment_prompt_for_toolcall(
+            initial_plan_decision = chatterer(
+                augment_prompt_for_toolcall(
                     function_signatures=function_signatures,
                     messages=context,
                     prompt_for_code_invoke=prompt_for_code_invoke,
                     function_reference_prefix=function_reference_prefix,
                     function_reference_seperator=function_reference_seperator,
                 ),
+                ThinkBeforeSpeak,
                 config=config,
                 stop=stop,
                 **kwargs,
@@ -350,4 +351,4 @@ def interactive_shell(
 
 
 if __name__ == "__main__":
-    interactive_shell()
+    interactive_shell(chatterer=Chatterer.openai())

chatterer/language_model.py

@@ -6,6 +6,7 @@ from typing import (
     Callable,
     Iterable,
     Iterator,
+    Literal,
     Optional,
     Self,
     Sequence,
@@ -20,7 +21,7 @@ from langchain_core.language_models.chat_models import BaseChatModel
 from langchain_core.runnables.base import Runnable
 from langchain_core.runnables.config import RunnableConfig
 from langchain_core.utils.utils import secret_from_env
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, SecretStr
 
 from .messages import AIMessage, BaseMessage, HumanMessage, UsageMetadata
 from .utils.code_agent import CodeExecutionResult, FunctionSignature, augment_prompt_for_toolcall
@@ -65,57 +66,80 @@ class Chatterer(BaseModel):
 
     @classmethod
     def from_provider(
-        cls,
-        provider_and_model: str,
-        structured_output_kwargs: Optional[dict[str, Any]] = {"strict": True},
+        cls, provider_and_model: str, structured_output_kwargs: Optional[dict[str, object]] = {"strict": True}
     ) -> Self:
         backend, model = provider_and_model.split(":", 1)
-        if backend == "openai":
-            return cls.openai(model=model, structured_output_kwargs=structured_output_kwargs)
-        elif backend == "anthropic":
-            return cls.anthropic(model_name=model, structured_output_kwargs=structured_output_kwargs)
-        elif backend == "google":
-            return cls.google(model=model, structured_output_kwargs=structured_output_kwargs)
-        elif backend == "ollama":
-            return cls.ollama(model=model, structured_output_kwargs=structured_output_kwargs)
-        elif backend == "openrouter":
-            return cls.open_router(model=model, structured_output_kwargs=structured_output_kwargs)
+        backends = cls.get_backends()
+        if func := backends.get(backend):
+            return func(model, structured_output_kwargs)
         else:
-            raise ValueError(f"Unsupported backend model: {backend}")
+            raise ValueError(f"Unsupported provider: {backend}. Supported providers are: {', '.join(backends.keys())}.")
+
+    @classmethod
+    def get_backends(cls) -> dict[str, Callable[[str, Optional[dict[str, object]]], Self]]:
+        return {
+            "openai": cls.openai,
+            "anthropic": cls.anthropic,
+            "google": cls.google,
+            "ollama": cls.ollama,
+            "openrouter": cls.open_router,
+            "xai": cls.xai,
+        }
 
     @classmethod
     def openai(
         cls,
-        model: str = "gpt-4o-mini",
-        structured_output_kwargs: Optional[dict[str, Any]] = {"strict": True},
+        model: str = "gpt-4.1",
+        structured_output_kwargs: Optional[dict[str, object]] = {"strict": True},
+        api_key: Optional[str] = None,
+        **kwargs: Any,
     ) -> Self:
         from langchain_openai import ChatOpenAI
 
-        return cls(client=ChatOpenAI(model=model), structured_output_kwargs=structured_output_kwargs or {})
+        return cls(
+            client=ChatOpenAI(
+                model=model,
+                api_key=_get_api_key(api_key=api_key, env_key="OPENAI_API_KEY", raise_if_none=False),
+                **kwargs,
+            ),
+            structured_output_kwargs=structured_output_kwargs or {},
+        )
 
     @classmethod
     def anthropic(
         cls,
         model_name: str = "claude-3-7-sonnet-20250219",
-        structured_output_kwargs: Optional[dict[str, Any]] = None,
+        structured_output_kwargs: Optional[dict[str, object]] = None,
+        api_key: Optional[str] = None,
+        **kwargs: Any,
     ) -> Self:
         from langchain_anthropic import ChatAnthropic
 
         return cls(
-            client=ChatAnthropic(model_name=model_name, timeout=None, stop=None),
+            client=ChatAnthropic(
+                model_name=model_name,
+                api_key=_get_api_key(api_key=api_key, env_key="ANTHROPIC_API_KEY", raise_if_none=True),
+                **kwargs,
+            ),
             structured_output_kwargs=structured_output_kwargs or {},
         )
 
     @classmethod
     def google(
         cls,
-        model: str = "gemini-2.0-flash",
-        structured_output_kwargs: Optional[dict[str, Any]] = None,
+        model: str = "gemini-2.5-flash-preview-04-17",
+        structured_output_kwargs: Optional[dict[str, object]] = None,
+        api_key: Optional[str] = None,
+        **kwargs: Any,
     ) -> Self:
         from langchain_google_genai import ChatGoogleGenerativeAI
 
         return cls(
-            client=ChatGoogleGenerativeAI(model=model),
+            client=ChatGoogleGenerativeAI(
+                model=model,
+                api_key=_get_api_key(api_key=api_key, env_key="GOOGLE_API_KEY", raise_if_none=False),
+                **kwargs,
+            ),
             structured_output_kwargs=structured_output_kwargs or {},
         )
 
@@ -123,12 +147,13 @@ class Chatterer(BaseModel):
     def ollama(
         cls,
         model: str = "deepseek-r1:1.5b",
-        structured_output_kwargs: Optional[dict[str, Any]] = None,
+        structured_output_kwargs: Optional[dict[str, object]] = None,
+        **kwargs: Any,
     ) -> Self:
         from langchain_ollama import ChatOllama
 
         return cls(
-            client=ChatOllama(model=model),
+            client=ChatOllama(model=model, **kwargs),
             structured_output_kwargs=structured_output_kwargs or {},
         )
 
@@ -136,7 +161,9 @@ class Chatterer(BaseModel):
     def open_router(
         cls,
         model: str = "openrouter/quasar-alpha",
-        structured_output_kwargs: Optional[dict[str, Any]] = None,
+        structured_output_kwargs: Optional[dict[str, object]] = None,
+        api_key: Optional[str] = None,
+        **kwargs: Any,
     ) -> Self:
         from langchain_openai import ChatOpenAI
 
@@ -144,7 +171,29 @@ class Chatterer(BaseModel):
             client=ChatOpenAI(
                 model=model,
                 base_url="https://openrouter.ai/api/v1",
-                api_key=secret_from_env("OPENROUTER_API_KEY", default=None)(),
+                api_key=_get_api_key(api_key=api_key, env_key="OPENROUTER_API_KEY", raise_if_none=False),
+                **kwargs,
+            ),
+            structured_output_kwargs=structured_output_kwargs or {},
+        )
+
+    @classmethod
+    def xai(
+        cls,
+        model: str = "grok-3-mini",
+        structured_output_kwargs: Optional[dict[str, object]] = None,
+        base_url: str = "https://api.x.ai/v1",
+        api_key: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Self:
+        from langchain_openai import ChatOpenAI
+
+        return cls(
+            client=ChatOpenAI(
+                model=model,
+                base_url=base_url,
+                api_key=_get_api_key(api_key=api_key, env_key="XAI_API_KEY", raise_if_none=False),
+                **kwargs,
             ),
             structured_output_kwargs=structured_output_kwargs or {},
         )
@@ -367,7 +416,7 @@ class Chatterer(BaseModel):
                 "total_tokens": approx_tokens,
             }
 
-    def invoke_code_execution(
+    def exec(
         self,
         messages: LanguageModelInput,
         repl_tool: Optional["PythonAstREPLTool"] = None,
@@ -401,7 +450,12 @@ class Chatterer(BaseModel):
             **kwargs,
         )
 
-    async def ainvoke_code_execution(
+    @property
+    def invoke_code_execution(self) -> Callable[..., CodeExecutionResult]:
+        """Alias for exec method for backward compatibility."""
+        return self.exec
+
+    async def aexec(
         self,
         messages: LanguageModelInput,
         repl_tool: Optional["PythonAstREPLTool"] = None,
@@ -432,6 +486,11 @@ class Chatterer(BaseModel):
             **kwargs,
         )
 
+    @property
+    def ainvoke_code_execution(self):
+        """Alias for aexec method for backward compatibility."""
+        return self.aexec
+
 
 class PythonCodeToExecute(BaseModel):
     code: str = Field(description="Python code to execute")
@@ -452,3 +511,23 @@ def _with_structured_output(
     structured_output_kwargs: dict[str, Any],
 ) -> Runnable[LanguageModelInput, dict[object, object] | BaseModel]:
     return client.with_structured_output(schema=response_model, **structured_output_kwargs)  # pyright: ignore[reportUnknownVariableType, reportUnknownMemberType]
+
+
+@overload
+def _get_api_key(api_key: Optional[str], env_key: str, raise_if_none: Literal[True]) -> SecretStr: ...
+@overload
+def _get_api_key(api_key: Optional[str], env_key: str, raise_if_none: Literal[False]) -> Optional[SecretStr]: ...
+def _get_api_key(api_key: Optional[str], env_key: str, raise_if_none: bool) -> Optional[SecretStr]:
+    if api_key is None:
+        api_key_found: SecretStr | None = secret_from_env(env_key, default=None)()
+        if raise_if_none and api_key_found is None:
+            raise ValueError(
+                (
+                    f"Did not find API key, please add an environment variable"
+                    f" `{env_key}` which contains it, or pass"
+                    f" api_key as a named parameter."
+                )
+            )
+        return api_key_found
+    else:
+        return SecretStr(api_key)

chatterer/utils/__init__.py

@@ -1,5 +1,4 @@
 from .base64_image import Base64Image
-from .cli import ArgumentSpec, BaseArguments
 from .code_agent import (
     CodeExecutionResult,
     FunctionSignature,
@@ -13,6 +12,4 @@ __all__ = [
     "CodeExecutionResult",
     "get_default_repl_tool",
     "insert_callables_into_global",
-    "BaseArguments",
-    "ArgumentSpec",
 ]

{chatterer-0.1.14.dist-info → chatterer-0.1.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chatterer
-Version: 0.1.14
+Version: 0.1.17
 Summary: The highest-level interface for various LLM APIs.
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -9,15 +9,18 @@ Requires-Dist: langchain>=0.3.19
 Requires-Dist: langchain-openai>=0.3.11
 Requires-Dist: pillow>=11.1.0
 Requires-Dist: regex>=2024.11.6
+Requires-Dist: rich>=13.9.4
 Provides-Extra: dev
 Requires-Dist: neo4j-extension>=0.1.14; extra == "dev"
 Requires-Dist: colorama>=0.4.6; extra == "dev"
 Requires-Dist: ipykernel>=6.29.5; extra == "dev"
+Requires-Dist: spargear>=0.1.4; extra == "dev"
 Provides-Extra: conversion
 Requires-Dist: youtube-transcript-api>=1.0.3; extra == "conversion"
 Requires-Dist: chatterer[browser]; extra == "conversion"
 Requires-Dist: chatterer[pdf]; extra == "conversion"
 Requires-Dist: chatterer[markdown]; extra == "conversion"
+Requires-Dist: chatterer[video]; extra == "conversion"
 Provides-Extra: browser
 Requires-Dist: playwright>=1.50.0; extra == "browser"
 Provides-Extra: pdf
@@ -28,6 +31,8 @@ Requires-Dist: markitdown[all]>=0.1.1; extra == "markdown"
 Requires-Dist: markdownify>=1.1.0; extra == "markdown"
 Requires-Dist: commonmark>=0.9.1; extra == "markdown"
 Requires-Dist: mistune>=3.1.3; extra == "markdown"
+Provides-Extra: video
+Requires-Dist: pydub>=0.25.1; extra == "video"
 Provides-Extra: langchain
 Requires-Dist: chatterer[langchain-providers]; extra == "langchain"
 Requires-Dist: langchain-experimental>=0.3.4; extra == "langchain"

{chatterer-0.1.14.dist-info → chatterer-0.1.17.dist-info}/RECORD

@@ -1,6 +1,6 @@
-chatterer/__init__.py,sha256=Mxt_qGUyLEbbJ3VU-qr1EBgE2tSNFvqxiL-1QcXLu2c,2252
-chatterer/interactive.py,sha256=4_XKcdpRNLWEbEXwszJG-sECGun7_U1tEhd30brUPZM,16784
-chatterer/language_model.py,sha256=L3mVbbtiRoUx1UfJy0gCJ4laf03nyfDiDQtbEcB5Nv0,17594
+chatterer/__init__.py,sha256=KmoWOad8UgqYeBCYXhFeeXCL9lzaB-Aa3KVqoAaXrMg,2174
+chatterer/interactive.py,sha256=JTtIUbG_ABqmSKyQT_0vkq_K09ZCv4nyr_pAEMqhk88,16780
+chatterer/language_model.py,sha256=j4MBUeHtifbufXyFUpKnxTlMbCwRQSgIgGmL09M4ifE,20126
 chatterer/messages.py,sha256=SIvG9hMHaPG4AFadeRbj5yPnMq2J06fHA4D8jrkz4kQ,458
 chatterer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 chatterer/common_types/__init__.py,sha256=Ais0kqzQJj4sED24xdv5azIxHkkj0vXWb4LC41dFkBQ,355
@@ -22,13 +22,12 @@ chatterer/tools/citation_chunking/citations.py,sha256=BWhSwzZccvu0Db-OxEbsuEGEz-
 chatterer/tools/citation_chunking/prompt.py,sha256=so-8uFQ5b2Zq2V5Brfxd76bEnKYkHovYsohAnbxWEnY,7557
 chatterer/tools/citation_chunking/reference.py,sha256=m47XYaB5uFff_x_k7US9hNr-SpZjKnl-GuzsGaQzcZo,893
 chatterer/tools/citation_chunking/utils.py,sha256=Xytm9lMrS783Po1qWAdEJ8q7Q3l2UMzwHd9EkYTRiwk,6210
-chatterer/utils/__init__.py,sha256=wA_nd1si3MbypA4biQRa3MYBqkHwTSCioYgaHce42Ls,412
+chatterer/utils/__init__.py,sha256=of2NeLOjsAI79TgA4bL7UggCnAc7xT9eu3eeUBt9K8k,326
 chatterer/utils/base64_image.py,sha256=w5SQoHVPDEQtFSUhV1l9GKg-IQy1WK5nyjv9k0upow8,10839
 chatterer/utils/bytesio.py,sha256=QabdJCZsabPaiYVfJcdXzdiHjuhqDlz1vJuLJ60P7TY,2559
-chatterer/utils/cli.py,sha256=F-Ooz4_pFeX4Y36R7OGhNrE7-IDyVIv2EEelYwJ4H0Y,19392
 chatterer/utils/code_agent.py,sha256=3Wu0M6VvfvWKu4UUoJ0rV-WjvLj06r15_01vft3d1Ns,10231
 chatterer/utils/imghdr.py,sha256=aZ1_AsRzyTsbV7uoeAZMVaC-hj73kvnFHMdHtFKskdE,3694
-chatterer-0.1.14.dist-info/METADATA,sha256=nMitUtZcmWPpmwVl_MTuzvK_AK-t6CuFlsdIxiSmbfA,11267
-chatterer-0.1.14.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-chatterer-0.1.14.dist-info/top_level.txt,sha256=7nSQKP0bHxPRc7HyzdbKsJdkvPgYD0214o6slRizv9s,10
-chatterer-0.1.14.dist-info/RECORD,,
+chatterer-0.1.17.dist-info/METADATA,sha256=tz1IPuxw7BSJR4N5SpT9FFE5Y9qE9twW9Hoxw18XF1I,11466
+chatterer-0.1.17.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+chatterer-0.1.17.dist-info/top_level.txt,sha256=7nSQKP0bHxPRc7HyzdbKsJdkvPgYD0214o6slRizv9s,10
+chatterer-0.1.17.dist-info/RECORD,,

{chatterer-0.1.14.dist-info → chatterer-0.1.17.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.1.0)
+Generator: setuptools (80.3.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

chatterer/utils/cli.py

@@ -1,476 +0,0 @@
-import argparse
-import io
-import typing
-import warnings
-from dataclasses import dataclass, field, fields
-from typing import (
-    IO,
-    Callable,
-    Dict,
-    Generic,
-    Iterable,
-    List,
-    Literal,
-    NamedTuple,
-    Optional,
-    Sequence,
-    Tuple,
-    TypeVar,
-    Union,
-)
-
-# --- Type Definitions ---
-SUPPRESS_LITERAL_TYPE = Literal["==SUPPRESS=="]
-SUPPRESS: SUPPRESS_LITERAL_TYPE = "==SUPPRESS=="
-ACTION_TYPES_THAT_DONT_SUPPORT_TYPE_KWARG = (
-    "store_const",
-    "store_true",
-    "store_false",
-    "append_const",
-    "count",
-    "help",
-    "version",
-)
-Action = Optional[
-    Literal[
-        "store",
-        "store_const",
-        "store_true",
-        "store_false",
-        "append",
-        "append_const",
-        "count",
-        "help",
-        "version",
-        "extend",
-    ]
-]
-T = TypeVar("T")
-
-
-@dataclass
-class ArgumentSpec(Generic[T]):
-    """Represents the specification for a command-line argument."""
-
-    name_or_flags: List[str]
-    action: Action = None
-    nargs: Optional[Union[int, Literal["*", "+", "?"]]] = None
-    const: Optional[object] = None
-    default: Optional[Union[T, SUPPRESS_LITERAL_TYPE]] = None
-    choices: Optional[Sequence[T]] = None
-    required: bool = False
-    help: str = ""
-    metavar: Optional[str] = None
-    version: Optional[str] = None
-    type: Optional[Union[Callable[[str], T], argparse.FileType]] = None
-    value: Optional[T] = field(init=False, default=None)  # Parsed value stored here
-
-    @property
-    def value_not_none(self) -> T:
-        """Returns the value, raising an error if it's None."""
-        if self.value is None:
-            raise ValueError(f"Value for {self.name_or_flags} is None.")
-        return self.value
-
-    def get_add_argument_kwargs(self) -> Dict[str, object]:
-        """Prepares keyword arguments for argparse.ArgumentParser.add_argument."""
-        kwargs: Dict[str, object] = {}
-        argparse_fields: set[str] = {f.name for f in fields(self) if f.name not in ("name_or_flags", "value")}
-        for field_name in argparse_fields:
-            attr_value = getattr(self, field_name)
-            if field_name == "default":
-                if attr_value is None:
-                    pass  # Keep default=None if explicitly set or inferred
-                elif attr_value in get_args(SUPPRESS_LITERAL_TYPE):
-                    kwargs[field_name] = argparse.SUPPRESS
-                else:
-                    kwargs[field_name] = attr_value
-            elif attr_value is not None:
-                if field_name == "type" and self.action in ACTION_TYPES_THAT_DONT_SUPPORT_TYPE_KWARG:
-                    continue
-                kwargs[field_name] = attr_value
-        return kwargs
-
-
-class ArgumentSpecType(NamedTuple):
-    T: object  # The T in ArgumentSpec[T]
-    element_type: typing.Optional[typing.Type[object]]  # The E in ArgumentSpec[List[E]] or ArgumentSpec[Tuple[E]]
-
-    @classmethod
-    def from_hint(cls, hints: Dict[str, object], attr_name: str):
-        if (
-            (hint := hints.get(attr_name))
-            and (hint_origin := get_origin(hint))
-            and (hint_args := get_args(hint))
-            and isinstance(hint_origin, type)
-            and issubclass(hint_origin, ArgumentSpec)
-        ):
-            T: object = hint_args[0]  # Extract T
-            element_type: typing.Optional[object] = None
-            if isinstance(outer_origin := get_origin(T), type):
-                if issubclass(outer_origin, list) and (args := get_args(T)):
-                    element_type = args[0]  # Extract E
-                elif issubclass(outer_origin, tuple) and (args := get_args(T)):
-                    element_type = args  # Extract E
-                else:
-                    element_type = None  # The E in ArgumentSpec[List[E]] or Tuple[E, ...]
-                if not isinstance(element_type, type):
-                    element_type = None
-            return cls(T=T, element_type=element_type)
-
-    @property
-    def choices(self) -> typing.Optional[Tuple[object, ...]]:
-        # ArgumentSpec[Literal["A", "B"]] or ArgumentSpec[List[Literal["A", "B"]]]
-        T_origin = get_origin(self.T)
-        if (
-            isinstance(T_origin, type)
-            and (issubclass(T_origin, (list, tuple)))
-            and (args := get_args(self.T))
-            and (get_origin(arg := args[0]) is typing.Literal)
-            and (literals := get_args(arg))
-        ):
-            return literals
-        elif T_origin is typing.Literal and (args := get_args(self.T)):
-            return args
-
-    @property
-    def type(self) -> typing.Optional[typing.Type[object]]:
-        if self.element_type is not None:
-            return self.element_type  # If it's List[E] or Sequence[E], use E as type
-        elif self.T and isinstance(self.T, type):
-            return self.T  # Use T as type
-
-    @property
-    def should_return_as_list(self) -> bool:
-        """Determines if the argument should be returned as a list."""
-        T_origin = get_origin(self.T)
-        if isinstance(T_origin, type):
-            if issubclass(T_origin, list):
-                return True
-        return False
-
-    @property
-    def should_return_as_tuple(self) -> bool:
-        """Determines if the argument should be returned as a tuple."""
-        T_origin = get_origin(self.T)
-        if isinstance(T_origin, type):
-            if issubclass(T_origin, tuple):
-                return True
-        return False
-
-    @property
-    def tuple_nargs(self) -> Optional[int]:
-        if self.should_return_as_tuple and (args := get_args(self.T)) and Ellipsis not in args:
-            return len(args)
-
-
-class BaseArguments:
-    """Base class for defining arguments declaratively using ArgumentSpec."""
-
-    __argspec__: Dict[str, ArgumentSpec[object]]
-    __argspectype__: Dict[str, ArgumentSpecType]
-
-    def __init_subclass__(cls, **kwargs: object) -> None:
-        """
-        Processes ArgumentSpec definitions in subclasses upon class creation.
-        Automatically infers 'type' and 'choices' from type hints if possible.
-        """
-        super().__init_subclass__(**kwargs)
-        cls.__argspec__ = {}
-        cls.__argspectype__ = {}
-        for current_cls in reversed(cls.__mro__):
-            if current_cls is object or current_cls is BaseArguments:
-                continue
-            current_vars = vars(current_cls)
-            try:
-                hints: Dict[str, object] = typing.get_type_hints(current_cls, globalns=dict(current_vars))
-                for attr_name, attr_value in current_vars.items():
-                    if isinstance(attr_value, ArgumentSpec):
-                        attr_value = typing.cast(ArgumentSpec[object], attr_value)
-                        if arguments_spec_type := ArgumentSpecType.from_hint(hints=hints, attr_name=attr_name):
-                            cls.__argspectype__[attr_name] = arguments_spec_type
-                            if attr_value.choices is None and (literals := arguments_spec_type.choices):
-                                attr_value.choices = literals
-                            if attr_value.type is None and (type := arguments_spec_type.type):
-                                attr_value.type = type
-                            if tuple_nargs := arguments_spec_type.tuple_nargs:
-                                attr_value.nargs = tuple_nargs
-                        cls.__argspec__[attr_name] = attr_value
-            except Exception as e:
-                warnings.warn(f"Could not fully analyze type hints for {current_cls.__name__}: {e}", stacklevel=2)
-                for attr_name, attr_value in current_vars.items():
-                    if isinstance(attr_value, ArgumentSpec) and attr_name not in cls.__argspec__:
-                        cls.__argspec__[attr_name] = attr_value
-
-    @classmethod
-    def iter_specs(cls) -> Iterable[Tuple[str, ArgumentSpec[object]]]:
-        """Iterates over the registered (attribute_name, ArgumentSpec) pairs."""
-        yield from cls.__argspec__.items()
-
-    @classmethod
-    def get_parser(cls) -> argparse.ArgumentParser:
-        """Creates and configures an ArgumentParser based on the defined ArgumentSpecs."""
-        arg_parser = argparse.ArgumentParser(
-            description=cls.__doc__,  # Use class docstring as description
-            formatter_class=argparse.ArgumentDefaultsHelpFormatter,
-            add_help=False,  # Add custom help argument later
-        )
-        # Add standard help argument
-        arg_parser.add_argument(
-            "-h", "--help", action="help", default=argparse.SUPPRESS, help="Show this help message and exit."
-        )
-        # Add arguments to the parser based on registered ArgumentSpecs
-        for key, spec in cls.iter_specs():
-            kwargs = spec.get_add_argument_kwargs()
-            # Determine if it's a positional or optional argument
-            is_positional: bool = not any(name.startswith("-") for name in spec.name_or_flags)
-            if is_positional:
-                # For positional args: remove 'required' (implicit), let argparse derive 'dest'
-                kwargs.pop("required", None)
-                try:
-                    arg_parser.add_argument(*spec.name_or_flags, **kwargs)  # pyright: ignore[reportArgumentType]
-                except Exception as e:
-                    # Provide informative error message
-                    raise ValueError(
-                        f"Error adding positional argument '{key}' with spec {spec.name_or_flags} and kwargs {kwargs}: {e}"
-                    ) from e
-            else:  # Optional argument
-                try:
-                    # For optional args: explicitly set 'dest' to the attribute name ('key')
-                    arg_parser.add_argument(*spec.name_or_flags, dest=key, **kwargs)  # pyright: ignore[reportArgumentType]
-                except Exception as e:
-                    # Provide informative error message
-                    raise ValueError(
-                        f"Error adding optional argument '{key}' with spec {spec.name_or_flags} and kwargs {kwargs}: {e}"
-                    ) from e
-        return arg_parser
-
-    @classmethod
-    def load(cls, args: Optional[Sequence[str]] = None) -> None:
-        """
-        Parses command-line arguments and assigns the values to the corresponding ArgumentSpec instances.
-        If 'args' is None, uses sys.argv[1:].
-        """
-        parser = cls.get_parser()
-        try:
-            parsed_args = parser.parse_args(args)
-        except SystemExit as e:
-            # Allow SystemExit (e.g., from --help) to propagate
-            raise e
-        # Assign parsed values from the namespace
-        cls.load_from_namespace(parsed_args)
-
-    @classmethod
-    def load_from_namespace(cls, args: argparse.Namespace) -> None:
-        """Assigns values from a parsed argparse.Namespace object to the ArgumentSpecs."""
-        for key, spec in cls.iter_specs():
-            # Determine the attribute name in the namespace
-            # Positional args use their name, optionals use the 'dest' (which is 'key')
-            is_positional = not any(name.startswith("-") for name in spec.name_or_flags)
-            attr_name = spec.name_or_flags[0] if is_positional else key
-            # Check if the attribute exists in the namespace
-            if not hasattr(args, attr_name):
-                continue
-
-            value: object = getattr(args, attr_name)
-            if value is argparse.SUPPRESS:
-                continue
-
-            # Assign the value unless it's the SUPPRESS sentinel
-            if argument_spec_type := cls.__argspectype__.get(key):
-                if argument_spec_type.should_return_as_list:
-                    if isinstance(value, list):
-                        value = typing.cast(List[object], value)
-                    elif value is not None:
-                        value = [value]
-                elif argument_spec_type.should_return_as_tuple:
-                    if isinstance(value, tuple):
-                        value = typing.cast(Tuple[object, ...], value)
-                    elif value is not None:
-                        if isinstance(value, list):
-                            value = tuple(typing.cast(List[object], value))
-                        else:
-                            value = (value,)
-            spec.value = value
-
-    @classmethod
-    def get_value(cls, key: str) -> Optional[object]:
-        """Retrieves the parsed value for a specific argument by its attribute name."""
-        if key in cls.__argspec__:
-            return cls.__argspec__[key].value
-        raise KeyError(f"Argument spec with key '{key}' not found.")
-
-    @classmethod
-    def get_all_values(cls) -> Dict[str, Optional[object]]:
-        """Returns a dictionary of all argument attribute names and their parsed values."""
-        return {key: spec.value for key, spec in cls.iter_specs()}
-
-    def __init__(self) -> None:
-        self.load()
-
-
-def get_args(t: object) -> Tuple[object, ...]:
-    """Returns the arguments of a type or a generic type."""
-    return typing.get_args(t)
-
-
-def get_origin(t: object) -> typing.Optional[object]:
-    """Returns the origin of a type or a generic type."""
-    return typing.get_origin(t)
-
-
-# --- Main execution block (Example Usage) ---
-if __name__ == "__main__":
-
-    class __Arguments(BaseArguments):
-        """Example argument parser demonstrating various features."""
-
-        my_str_arg: ArgumentSpec[str] = ArgumentSpec(
-            ["-s", "--string-arg"], default="Hello", help="A string argument.", metavar="TEXT"
-        )
-        my_int_arg: ArgumentSpec[int] = ArgumentSpec(
-            ["-i", "--integer-arg"], required=True, help="A required integer argument."
-        )
-        verbose: ArgumentSpec[bool] = ArgumentSpec(
-            ["-v", "--verbose"], action="store_true", help="Increase output verbosity."
-        )
-        # --- List<str> ---
-        my_list_arg: ArgumentSpec[List[str]] = ArgumentSpec(
-            ["--list-values"],
-            nargs="+",
-            help="One or more string values.",
-            default=None,
-        )
-        # --- Positional IO ---
-        input_file: ArgumentSpec[IO[str]] = ArgumentSpec(
-            ["input_file"],
-            type=argparse.FileType("r", encoding="utf-8"),
-            help="Path to the input file (required).",
-            metavar="INPUT_PATH",
-        )
-        output_file: ArgumentSpec[Optional[IO[str]]] = ArgumentSpec(
-            ["output_file"],
-            type=argparse.FileType("w", encoding="utf-8"),
-            nargs="?",
-            default=None,
-            help="Optional output file path.",
-            metavar="OUTPUT_PATH",
-        )
-        # --- Simple Literal (choices auto-detected) ---
-        log_level: ArgumentSpec[Literal["DEBUG", "INFO", "WARNING", "ERROR"]] = ArgumentSpec(
-            ["--log-level"],
-            default="INFO",
-            help="Set the logging level.",
-        )
-        # --- Literal + explicit choices (explicit wins) ---
-        mode: ArgumentSpec[Literal["fast", "slow", "careful"]] = ArgumentSpec(
-            ["--mode"],
-            choices=["fast", "slow"],  # Explicit choices override Literal args
-            default="fast",
-            help="Operation mode.",
-        )
-        # --- List[Literal] (choices auto-detected) ---
-        enabled_features: ArgumentSpec[List[Literal["CACHE", "LOGGING", "RETRY"]]] = ArgumentSpec(
-            ["--features"],
-            nargs="*",  # 0 or more features
-            help="Enable specific features.",
-            default=[],
-        )
-        tuple_features: ArgumentSpec[
-            Tuple[Literal["CACHE", "LOGGING", "RETRY"], Literal["CAwCHE", "LOGGING", "RETRY"]]
-        ] = ArgumentSpec(
-            ["--tuple-features"],
-            help="Enable specific features (tuple).",
-        )
-
-        # --- SUPPRESS default ---
-        optional_flag: ArgumentSpec[str] = ArgumentSpec(
-            ["--opt-flag"],
-            default=SUPPRESS,
-            help="An optional flag whose attribute might not be set.",
-        )
-
-    print("--- Initial State (Before Parsing) ---")
-    parser_for_debug = __Arguments.get_parser()
-    for k, s in __Arguments.iter_specs():
-        print(f"{k}: value={s.value}, type={s.type}, choices={s.choices}")  # Check inferred choices
-
-    dummy_input_filename = "temp_input_for_argparse_test.txt"
-    try:
-        with open(dummy_input_filename, "w", encoding="utf-8") as f:
-            f.write("This is a test file.\n")
-        print(f"\nCreated dummy input file: {dummy_input_filename}")
-    except Exception as e:
-        print(f"Warning: Could not create dummy input file '{dummy_input_filename}': {e}")
-
-    # Example command-line arguments (Adjusted order)
-    test_args = [
-        dummy_input_filename,
-        "-i",
-        "42",
-        "--log-level",
-        "WARNING",
-        "--mode",
-        "slow",
-        "--list-values",
-        "apple",
-        "banana",
-        "--features",
-        "CACHE",
-        "RETRY",  # Test List[Literal]
-        "--tuple-features",
-        "CACHE",
-        "LOGGING",  # Test Tuple[Literal]
-    ]
-    # test_args = ['--features', 'INVALID'] # Test invalid choice for List[Literal]
-    # test_args = ['-h']
-
-    try:
-        print(f"\n--- Loading Arguments (Args: {test_args if test_args else 'from sys.argv'}) ---")
-        __Arguments.load(test_args)
-        print("\n--- Final Loaded Arguments ---")
-        all_values = __Arguments.get_all_values()
-        for key, value in all_values.items():
-            value_type = type(value).__name__
-            if isinstance(value, io.IOBase):
-                try:
-                    name = getattr(value, "name", "<unknown_name>")
-                    mode = getattr(value, "mode", "?")
-                    value_repr = f"<IO {name} mode='{mode}'>"
-                except ValueError:
-                    value_repr = "<IO object (closed)>"
-            else:
-                value_repr = repr(value)
-            print(f"{key}: {value_repr} (Type: {value_type})")
-
-        print("\n--- Accessing Specific Values ---")
-        print(f"Features     : {__Arguments.get_value('enabled_features')}")  # Check List[Literal] value
-
-        input_f = __Arguments.get_value("input_file")
-        if isinstance(input_f, io.IOBase):
-            try:
-                print(f"\nReading from input file: {input_f.name}")  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
-                input_f.close()
-                print(f"Closed input file: {input_f.name}")  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
-            except Exception as e:
-                print(f"Error processing input file: {e}")
-
-    except SystemExit as e:
-        print(f"\nExiting application (SystemExit code: {e.code}).")
-    except FileNotFoundError as e:
-        print(f"\nError: Required file not found: {e.filename}")
-        parser_for_debug.print_usage()
-    except Exception as e:
-        print(f"\nAn unexpected error occurred: {e}")
-        import traceback
-
-        traceback.print_exc()
-    finally:
-        import os
-
-        if os.path.exists(dummy_input_filename):
-            try:
-                os.remove(dummy_input_filename)
-                print(f"\nRemoved dummy input file: {dummy_input_filename}")
-            except Exception as e:
-                print(f"Warning: Could not remove dummy file '{dummy_input_filename}': {e}")