Base

def add_arg(self, arg: InstanceArgument | str, tabs: int = 0) -> None:
    """Add an extra argument.

    Parameters
    ----------
    arg : InstanceArgument
        The argument to add.
    tabs : int, optional
        The number of tabs to indent the argument, by default 0.
    """
    if isinstance(arg, InstanceArgument):
        if arg not in self.extra_args:
            self.extra_args.append(arg)
    elif isinstance(arg, str) and arg.strip():  # pyright: ignore
        # If it's a string, create an InstanceArgument
        # split by '=' (it's an argument line)
        parts = arg.split("=", 1)
        if len(parts) == 2:
            name, value = parts
            comment = ""
            if " #" in value:
                value, _comment = value.split(" #", 1)
                comment = _comment.strip()
            new_arg = InstanceArgument(
                instance_id=self.instance_id,
                name=name.strip(),
                value=value.strip(),
                tabs=tabs,
                comment=comment.strip(),
            )
            if new_arg not in self.extra_args:
                self.extra_args.append(new_arg)

def add_import(self, import_statement: ImportStatement) -> None:
    """Add an import statement.

    Parameters
    ----------
    import_statement : str
        The import statement to add.
    """
    if import_statement and import_statement.statement.strip():
        self.extra_imports.append(import_statement)

def add_imports(self, imports: Sequence[ImportStatement]) -> None:
    """Add multiple import statements.

    Parameters
    ----------
    imports : Set[str]
        The import statements to add.
    """
    for imp in imports:
        self.add_import(imp)

def append_after_agent(self, content: str) -> None:
    """Append content to the after_agent section.

    Parameters
    ----------
    content : str
        The content to append.
    """
    if content and content.strip():
        if self.after_agent:
            self.after_agent += "\n" + content.rstrip()
        else:
            self.after_agent = content.rstrip()

def append_after_all_agents(self, content: str) -> None:
    """Append content to the after_all_agents section.

    Parameters
    ----------
    content : str
        The content to append.
    """
    if content and content.strip():
        if self.after_all_agents:
            self.after_all_agents += "\n" + content.rstrip()
        else:
            self.after_all_agents = content.rstrip()

def append_before_agent(self, content: str) -> None:
    """Append content to the before_agent section.

    Parameters
    ----------
    content : str
        The content to append.
    """
    if content and content.strip():
        if self.before_agent:
            self.before_agent += "\n" + content.rstrip()
        else:
            self.before_agent = content.rstrip()

def contribute_to_export(self, result: ExportResult) -> None:
    """Contribute this extras' content to the export result.

    Parameters
    ----------
    result : ExportResult
        The export result to contribute to.
    """
    # Add imports
    result.add_imports(self.extra_imports, ImportPosition.THIRD_PARTY)

    # Add before/after content with default positioning
    # Subclasses can override this method for custom positioning
    if self.before_agent:
        result.add_content(
            self.before_agent,
            ExportPosition.AGENTS,
            order=ContentOrder.PRE_CONTENT,
        )

    if self.extra_args:
        for arg in self.extra_args:
            result.add_content(
                arg.get_content(),
                ExportPosition.AGENTS,
                order=ContentOrder.MAIN_CONTENT,
                agent_position=AgentPosition.AS_ARGUMENT,
            )

    if self.after_agent:
        result.add_content(
            self.after_agent,
            ExportPosition.AGENTS,
            order=ContentOrder.POST_CONTENT,
        )

    # Allow subclasses to contribute additional content
    self._contribute_specific_content(result)

def get_extra_args_content(self) -> str:
    """Get the extra arguments content.

    Returns
    -------
    str
        The extra arguments content.
    """
    return "\n".join([arg.get_content() for arg in self.extra_args]) + "\n"

def has_content(self) -> bool:
    """Check if there's any meaningful content.

    Returns
    -------
    bool
        True if there's any content in this extras instance.
    """
    return bool(
        self.extra_imports
        or self.before_agent.strip()
        or self.after_agent.strip()
        or self.has_specific_content()
    )

@abc.abstractmethod
def has_specific_content(self) -> bool:
    """Check if there's subclass-specific content.

    Returns
    -------
    bool
        True if there's specific content for this extras type.
    """

def prepend_after_all_agents(self, content: str) -> None:
    """Prepend content to the after_all_agents section.

    Parameters
    ----------
    content : str
        The content to prepend.
    """
    if content and content.strip():
        if self.after_all_agents:
            self.after_all_agents = (
                content.rstrip() + "\n" + self.after_all_agents
            )
        else:
            self.after_all_agents = content.rstrip()

def prepend_before_agent(self, content: str) -> None:
    """Prepend content to the before_agent section.

    Parameters
    ----------
    content : str
        The content to prepend.
    """
    if content and content.strip():
        if self.before_agent:
            self.before_agent = content.rstrip() + "\n" + self.before_agent
        else:
            self.before_agent = content.rstrip()

def has_specific_content(self) -> bool:
    """Check for captain specific content.

    Returns
    -------
    bool
        True if there's captain specific content.
    """
    if not super().has_specific_content():
        return bool(self.extra_args or self.nested_config)
    return True

def set_nested_config(self, config: dict[str, Any]) -> None:
    """Set the nested configuration.

    Parameters
    ----------
    config : Dict[str, Any]
        The nested configuration.
    """
    self.nested_config = config

def add_registration(self, registration: str) -> None:
    """Add chat registration content.

    Parameters
    ----------
    registration : str
        The chat registration content.
    """
    if registration and registration.strip():
        self.chat_registration += "\n" + registration.strip() + "\n"

def has_specific_content(self) -> bool:
    """Check for chat specific content.

    Returns
    -------
    bool
        True if there's chat specific content.
    """
    return bool(
        self.chat_initiation.strip()
        or self.chat_prerequisites.strip()
        or self.chat_registration.strip()
    )

def set_chat_initiation(self, initiation: str) -> None:
    """Set the chat initiation.

    Parameters
    ----------
    initiation : str
        The chat initiation content.
    """
    self.chat_initiation = initiation

def set_chat_prerequisites(self, prerequisites: str) -> None:
    """Set the chat prerequisites.

    Parameters
    ----------
    prerequisites : str
        The chat prerequisites content.
    """
    self.chat_prerequisites = prerequisites

def set_chat_registration(self, registration: str) -> None:
    """Set the chat registration.

    Parameters
    ----------
    registration : str
        The chat registration content.
    """
    self.chat_registration = registration

def has_content(self) -> bool:
    """Check if there's any code execution content.

    Returns
    -------
    bool
        True if there's any code execution configuration.
    """
    return bool(
        self.executor_content.strip()
        or self.executor_argument != "False"
        or self.executor_import
    )

def get_config_value(self, key: str, default: Any = None) -> Any:
    """Get a configuration value.

    Parameters
    ----------
    key : str
        The configuration key.
    default : Any, optional
        Default value if key not found, by default None

    Returns
    -------
    Any
        The configuration value or default.
    """
    return self._config.get(key, default)

def set_config_value(self, key: str, value: Any) -> None:
    """Set a configuration value.

    Parameters
    ----------
    key : str
        The configuration key.
    value : Any
        The configuration value.
    """
    self._config[key] = value

def generate(
    self,
    merged_result: ExportResult,
    is_async: bool,
    after_run: str,
    **kwargs: Any,
) -> str:  # pyright: ignore
    """Generate content based on provided parameters.

    Parameters
    ----------
    merged_result : ExportResult
        The merged export result containing all content.
    is_async : bool
        Whether to generate async content.
    after_run : str
        Additional content to add after the main flow execution.
    **kwargs : Any
        Parameters to influence content generation.

    Returns
    -------
    str
        The generated content.
    """

def resolve(self, path: str) -> str:
    """Resolve a path to a local file system path.

    Parameters
    ----------
    path : Union[str, Path]
        The path to resolve.

    Returns
    -------
    Optional[Path]
        The resolved local path or None if not found.
    """
    resolved = _check_local_path(path)
    if not resolved:
        return _get_raw_path_string(path)
    return _get_raw_path_string(resolved)

def serialize(self, obj: Any, **kwargs: Any) -> str:
    """Serialize an item to a formatted string.

    Parameters
    ----------
    obj : Any
        The item to serialize.
    **kwargs : Any
        Additional keyword arguments, such as `tabs` for indentation level.

    Returns
    -------
    str
        The serialized string representation of the item.
    """
    tabs = kwargs.get("tabs", 1)
    return serialize_item(obj, tabs)

def as_tuple(self) -> tuple[str, str]:
    """Get the environment variable as a tuple.

    Returns
    -------
    tuple[str, str]
        The environment variable as a tuple.
    """
    return (self.name, self.value)

@classmethod
def create(cls, **kwargs: Any) -> "ExportConfig":
    """Create a new ExportConfig instance with the provided values.

    Parameters
    ----------
    **kwargs : Any
        Keyword arguments to initialize the ExportConfig.

    Returns
    -------
    ExportConfig
        A new instance of ExportConfig.
    """
    valid_fields = {f.name for f in fields(cls)}
    output_extension = kwargs.pop("output_extension", "py")
    for_notebook = kwargs.pop("for_notebook", output_extension == "ipynb")
    if for_notebook is True:
        output_extension = "ipynb"
    cache_seed = kwargs.pop("cache_seed", None)
    if cache_seed is not None and not isinstance(cache_seed, int):
        cache_seed = None
    return cls(
        cache_seed=cache_seed,
        output_extension=output_extension,
        **{k: v for k, v in kwargs.items() if k in valid_fields},
    )

def update(self, **kwargs: Any) -> None:
    """Update the export configuration with new values.

    Parameters
    ----------
    **kwargs : Any
        Keyword arguments to update the configuration.

    Raises
    ------
    ValueError
        If an invalid configuration key is provided.
    """
    valid_fields = {f.name for f in fields(self)}
    for key, value in kwargs.items():
        if key in valid_fields:
            setattr(self, key, value)
    if (
        "for_notebook" in kwargs
        and isinstance(kwargs["for_notebook"], bool)
        and "output_extension" not in kwargs
    ):  # pragma: no cover
        self.output_extension = "ipynb" if kwargs["for_notebook"] else "py"

def contribute_to_export(self, result: ExportResult) -> None:
    """Contribute content to the export result.

    Parameters
    ----------
    result : ExportResult
        The export result to contribute to.
    """

def add_content(
    self,
    content: str,
    position: ExportPosition = DEFAULT_EXPORT_POSITION,
    order: Union[ContentOrder, int] = ContentOrder.MAIN_CONTENT,
    skip_strip: bool = False,
    agent_id: Optional[str] = None,
    agent_position: Optional[AgentPosition] = None,
    metadata: Optional[dict[str, Any]] = None,
) -> None:
    """Add positioned content.

    Parameters
    ----------
    content : str
        The content to add.
    position : ExportPosition, optional
        The position of the content, by default AGENTS
    order : int, optional
        The order within the position, by default 0
    skip_strip : bool, optional
        Whether to skip stripping whitespace from content, by default False
    agent_id : Optional[str], optional
        The agent ID if positioned relative to an agent, by default None
    agent_position : Optional[AgentPosition], optional
        The position relative to the agent, by default None
    metadata : Optional[dict[str, Any]], optional
        Additional metadata for the content, by default None
    """
    order_value = order.value if isinstance(order, ContentOrder) else order
    if content and content.strip():
        positioned = PositionedContent(
            content=content.strip() if not skip_strip else content,
            position=position,
            order=order_value,
            agent_id=agent_id,
            agent_position=agent_position,
            **(metadata or {}),
        )
        if positioned not in self.positioned_content:
            self.positioned_content.append(positioned)

def add_env_var(
    self,
    name: str,
    value: str,
    description: Optional[str] = None,
    required: bool = True,
) -> None:
    """Add environment variable.

    Parameters
    ----------
    name : str
        The name of the environment variable.
    value : str
        The value of the environment variable.
    description : Optional[str], optional
        Description of the variable, by default None
    required : bool, optional
        Whether the variable is required, by default True
    """
    if name and value:
        env_var = EnvironmentVariable(
            name=name,
            value=value,
            description=description,
            required=required,
        )
        # Avoid duplicates based on name
        for existing in self.environment_variables:
            if existing.name == name:
                # Update existing
                existing.value = value
                existing.description = description
                existing.required = required
                return
        self.environment_variables.append(env_var)

def add_import(
    self, statement: str, position: ImportPosition = DEFAULT_IMPORT_POSITION
) -> None:
    """Add an import statement.

    Parameters
    ----------
    statement : str
        The import statement to add.
    position : ImportPosition, optional
        The position of the import, by default THIRD_PARTY
    """
    if statement and statement.strip():
        self.imports.add(
            ImportStatement(
                statement=statement.strip(),
                position=position,
            )
        )

def add_imports(
    self,
    statements: Union[
        set[str],
        list[str],
        set[ImportStatement],
        list[ImportStatement],
    ],
    position: ImportPosition = DEFAULT_IMPORT_POSITION,
) -> None:
    """Add multiple import statements.

    Parameters
    ----------
    statements : Union[
            set[str],
            list[str]],
            set[ImportStatement],
            list[ImportStatement]
        ]
        The import statements to add.
    position : ImportPosition, optional
        The position of the imports, by default THIRD_PARTY
    """
    for statement in statements:
        if isinstance(statement, ImportStatement):
            # If it's already an ImportStatement, use it directly
            self.add_import(statement.statement, statement.position)
        else:
            # Otherwise, treat it as a string
            self.add_import(statement, position)