ara-cli 0.1.10.5__py3-none-any.whl → 0.1.13.3__py3-none-any.whl

ara_cli/chat_agent/agent_process_manager.py

@@ -0,0 +1,155 @@
+import os
+
+try:
+    import pty
+except ImportError:
+    pty = None
+import sys
+import stat
+from ara_cli.error_handler import AraError, ErrorLevel
+
+
+class AgentProcessManager:
+    """
+    Manages the lifecycle of binary, interactive agents.
+    This manager is designed to run agents that require full TTY control,
+    handing over the terminal to the agent process until it exits.
+    """
+
+    def __init__(self, chat_instance=None):
+        self.chat_instance = chat_instance
+        self.agent_process = None
+
+    def get_agent_path(self, agent_name):
+        """
+        Constructs the full path to the agent binary by reliably finding
+        the project root.
+        """
+        if not self.chat_instance:
+            raise AraError("Chat instance is not available to find project root.")
+
+        base_dir = self.chat_instance._find_project_root()
+        if not base_dir:
+            raise AraError(
+                "Could not find project root from chat instance. Is this a valid ara project?"
+            )
+
+        return os.path.join(base_dir, "ara", ".araconfig", "agents", agent_name)
+
+    def _ensure_executable(self, agent_path):
+        """
+        Validates existence and ensures the binary is executable.
+        """
+        if (agent_path != "--help") and (not os.path.exists(agent_path)):
+            raise AraError(f"Agent binary not found at: {agent_path}")
+
+        if not os.path.isfile(agent_path):
+            raise AraError(f"Agent path does not point to a file: {agent_path}")
+
+        if not os.access(agent_path, os.X_OK):
+            try:
+                os.chmod(agent_path, os.stat(agent_path).st_mode | stat.S_IEXEC)
+                print(f"Made agent binary executable: {agent_path}")
+            except Exception as e:
+                raise AraError(
+                    f"Agent binary is not executable and could not be changed: {agent_path}. Error: {e}"
+                )
+
+    def _print_session_banner(self, agent_name, is_start=True):
+        """
+        Handles UI printing for start and end of sessions.
+        """
+        print("\n" + "=" * 50)
+        if is_start:
+            print(f"Starting interactive agent: {agent_name}")
+            print("You are now in an interactive session with the agent.")
+            print(
+                "To exit, use the agent's own exit command (e.g., '/quit', '/exit', or Ctrl+C)."
+            )
+            print("You will be returned to the 'ara>' prompt after the agent exits.")
+        else:
+            print("Returned to ara-cli prompt.")
+        print("=" * 50 + ("\n" if is_start else ""))
+
+        sys.stdout.flush()
+        sys.stderr.flush()
+
+    def _handle_process_exit(self, agent_name, return_code):
+        """
+        Analyzes the exit status code.
+        """
+        print("\n" + "=" * 50)
+
+        if pty:
+            if os.WIFEXITED(return_code):
+                exit_code = os.WEXITSTATUS(return_code)
+                status_msg = (
+                    f"Agent '{agent_name}' finished successfully."
+                    if exit_code == 0
+                    else f"Agent '{agent_name}' exited with code: {exit_code}."
+                )
+                print(status_msg)
+            elif os.WIFSIGNALED(return_code):
+                signal_num = os.WTERMSIG(return_code)
+                print(f"Agent '{agent_name}' terminated by signal: {signal_num}.")
+            else:
+                print(
+                    f"Agent '{agent_name}' exited with an unexpected status: {return_code}."
+                )
+        else:
+            # Windows/Non-pty fallback: return_code is the actual exit code
+            status_msg = (
+                f"Agent '{agent_name}' finished successfully."
+                if return_code == 0
+                else f"Agent '{agent_name}' exited with code: {return_code}."
+            )
+            print(status_msg)
+
+    def run_agent(self, agent_name, agent_args):
+        """
+        Finds, validates, and runs a binary agent using a pseudo-terminal (pty).
+        Refactored to maintain low CCN.
+        """
+        if os.name == "nt":
+            raise AraError(
+                "Agent execution is not supported on Windows platforms.",
+                level=ErrorLevel.WARNING,
+            )
+
+        agent_path = self.get_agent_path(agent_name)
+
+        # Validation Logic Extracted
+        self._ensure_executable(agent_path)
+
+        command = [agent_path] + agent_args
+
+        # UI Logic Extracted
+        self._print_session_banner(agent_name, is_start=True)
+
+        try:
+            # Execution Logic
+            if pty:
+                return_code = pty.spawn(command)
+            else:
+                # Fallback if pty is missing on non-Windows (unlikely but safe)
+                import subprocess
+
+                return_code = subprocess.call(command)
+
+            # Exit Status Logic Extracted
+            self._handle_process_exit(agent_name, return_code)
+
+        except FileNotFoundError:
+            raise AraError(f"Failed to execute. Command not found: {agent_path}")
+        except Exception as e:
+            raise AraError(f"An error occurred while trying to run the agent: {e}")
+        finally:
+            self._print_session_banner(agent_name, is_start=False)
+
+    def cleanup_agent_process(self):
+        """
+        Placeholder for cleanup.
+        """
+        if hasattr(self, "chat_instance") and self.chat_instance:
+            self.chat_instance.prompt = "ara> "
+        pass

ara_cli/chat_script_runner/script_completer.py

@@ -0,0 +1,23 @@
+from ara_cli.chat_script_runner.script_lister import ScriptLister
+
+class ScriptCompleter:
+    def __init__(self):
+        self.script_lister = ScriptLister()
+
+    def __call__(self, text, line, begidx, endidx):
+        if line.startswith("rpy global/"):
+            return self._complete_global_scripts(text)
+        
+        return self._complete_all_scripts(text)
+
+    def _complete_all_scripts(self, text):
+        all_scripts = self.script_lister.get_all_scripts()
+        if not text:
+            return all_scripts
+        return [s for s in all_scripts if s.startswith(text)]
+
+    def _complete_global_scripts(self, text):
+        global_scripts = self.script_lister.get_global_scripts()
+        if not text:
+            return global_scripts
+        return [s for s in global_scripts if s.startswith(text)]

ara_cli/chat_script_runner/script_finder.py

@@ -0,0 +1,41 @@
+import os
+from ara_cli.ara_config import ConfigManager
+
+
+class ScriptFinder:
+    def __init__(self):
+        config = ConfigManager.get_config()
+        # Convert to absolute path NOW, before any chdir operations
+        # This ensures scripts are found after Chat.start() changes cwd
+        self.local_prompt_templates_dir = os.path.abspath(
+            config.local_prompt_templates_dir
+        )
+
+    def get_custom_scripts_dir(self):
+        return os.path.join(self.local_prompt_templates_dir, "custom-scripts")
+
+    def get_global_scripts_dir(self):
+        return os.path.join(self.local_prompt_templates_dir, "global-scripts")
+
+    def find_script(self, script_name: str) -> str | None:
+        # Handle explicit global path for backward compatibility or specific cases
+        if script_name.startswith("global/"):
+            script_path = os.path.join(
+                self.get_global_scripts_dir(), script_name.replace("global/", ""))
+            if os.path.exists(script_path):
+                return script_path
+            return None
+
+        # 1. Search in custom-scripts first (allows overriding global scripts)
+        custom_script_path = os.path.join(
+            self.get_custom_scripts_dir(), script_name)
+        if os.path.exists(custom_script_path):
+            return custom_script_path
+
+        # 2. If not found in custom, fall back to global-scripts
+        global_script_path = os.path.join(
+            self.get_global_scripts_dir(), script_name)
+        if os.path.exists(global_script_path):
+            return global_script_path
+
+        return None

ara_cli/chat_script_runner/script_lister.py

@@ -0,0 +1,36 @@
+import os
+import glob
+from ara_cli.chat_script_runner.script_finder import ScriptFinder
+
+
+class ScriptLister:
+    def __init__(self):
+        self.script_finder = ScriptFinder()
+
+    def get_all_scripts(self):
+        custom_scripts = self.get_custom_scripts()
+        global_scripts = self.get_global_scripts()
+
+        # Custom scripts without prefix, global scripts with 'global/' prefix
+        prefixed_global_scripts = [f"global/{s}" for s in global_scripts]
+
+        # Return a single, sorted list for autocompletion
+        return sorted(custom_scripts + prefixed_global_scripts)
+
+    def get_custom_scripts(self):
+        custom_scripts_dir = self.script_finder.get_custom_scripts_dir()
+        if not custom_scripts_dir or not os.path.isdir(custom_scripts_dir):
+            return []
+        return [
+            os.path.basename(f)
+            for f in glob.glob(os.path.join(custom_scripts_dir, "*.py"))
+        ]
+
+    def get_global_scripts(self):
+        global_scripts_dir = self.script_finder.get_global_scripts_dir()
+        if not global_scripts_dir or not os.path.isdir(global_scripts_dir):
+            return []
+        return [
+            os.path.basename(f)
+            for f in glob.glob(os.path.join(global_scripts_dir, "*.py"))
+        ]

ara_cli/chat_script_runner/script_runner.py

@@ -0,0 +1,36 @@
+import os
+import subprocess
+from ara_cli.chat_script_runner.script_finder import ScriptFinder
+from ara_cli.chat_script_runner.script_lister import ScriptLister
+
+class ScriptRunner:
+    def __init__(self, chat_instance):
+        self.chat_instance = chat_instance
+        self.script_finder = ScriptFinder()
+        self.script_lister = ScriptLister()
+
+    def run_script(self, script_name: str, args: list[str] = None):
+        script_path = self.script_finder.find_script(script_name)
+        if not script_path:
+            return f"Script '{script_name}' not found."
+
+        command = ["python", script_path]
+        if args:
+            command.extend(args)
+
+        try:
+            result = subprocess.run(
+                command,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            return result.stdout
+        except subprocess.CalledProcessError as e:
+            return f"Error running script: {e}\n{e.stderr}"
+
+    def get_available_scripts(self):
+        return self.script_lister.get_all_scripts()
+
+    def get_global_scripts(self):
+        return self.script_lister.get_global_scripts()

ara_cli/chat_web_search/web_search.py

@@ -0,0 +1,263 @@
+"""
+Native web search implementation for OpenAI and Anthropic.
+Uses the default LLM from ara_config to determine which provider to use.
+Includes source citations at the end of search results.
+
+OpenAI API Compatibility:
+- Responses API: Uses `web_search` tool with models like gpt-5, o4-mini
+- Chat Completions: Uses specialized models gpt-5-search-api, gpt-4o-search-preview
+"""
+import os
+from typing import Generator, Tuple, Optional, List, Dict
+
+from ara_cli.prompt_handler import LLMSingleton
+from ara_cli.error_handler import AraError
+
+
+# OpenAI models that support web search via Responses API
+OPENAI_RESPONSES_API_MODELS = [
+    "gpt-5", "gpt-5.1", "gpt-5.2", "o3", "o4-mini",
+    "openai/gpt-5", "openai/gpt-5.1", "openai/gpt-5.2", "openai/o3", "openai/o4-mini",
+]
+
+# OpenAI models that use Chat Completions API with built-in search
+OPENAI_CHAT_COMPLETIONS_SEARCH_MODELS = [
+    "gpt-5-search-api", "gpt-4o-search-preview", "gpt-4o-mini-search-preview",
+    "openai/gpt-5-search-api", "openai/gpt-4o-search-preview", "openai/gpt-4o-mini-search-preview",
+]
+
+OPENAI_WEB_SEARCH_MODELS = OPENAI_RESPONSES_API_MODELS + \
+    OPENAI_CHAT_COMPLETIONS_SEARCH_MODELS
+
+ANTHROPIC_WEB_SEARCH_MODELS = [
+    "claude-sonnet-4-5-20250929", "claude-sonnet-4-20250514",
+    "claude-haiku-4-5-20251001", "claude-3-5-haiku-latest",
+    "claude-opus-4-5-20251101", "claude-opus-4-1-20250805", "claude-opus-4-20250514",
+    "anthropic/claude-sonnet-4-5-20250929", "anthropic/claude-sonnet-4-20250514",
+    "anthropic/claude-haiku-4-5-20251001",
+    "anthropic/claude-3-5-haiku-latest", "anthropic/claude-opus-4-5-20251101",
+    "anthropic/claude-opus-4-1-20250805", "anthropic/claude-opus-4-20250514",
+]
+
+
+def is_web_search_supported(model: str) -> Tuple[bool, Optional[str]]:
+    """Check if the model supports web search and return the provider."""
+    if model in OPENAI_WEB_SEARCH_MODELS:
+        return True, "openai"
+    if model in ANTHROPIC_WEB_SEARCH_MODELS:
+        return True, "anthropic"
+    return False, None
+
+
+def get_supported_models_message(model: str) -> str:
+    """Return a message listing all supported web search models."""
+    return (
+        f"Web search is not supported by the current default model: {model}\n"
+        "Please choose one of the following models:\n"
+        "==OpenAI (Responses API)==\n"
+        "\tgpt-5, gpt-5.1, gpt-5.2, o3, o4-mini\n"
+        "==OpenAI (Chat Completions)==\n"
+        "\tgpt-5-search-api, gpt-4o-search-preview, gpt-4o-mini-search-preview\n"
+        "==Anthropic==\n"
+        "\tclaude-sonnet-4-5-20250929, claude-sonnet-4-20250514\n"
+        "\tclaude-haiku-4-5-20251001, claude-3-5-haiku-latest\n"
+        "\tclaude-opus-4-5-20251101, claude-opus-4-1-20250805, claude-opus-4-20250514\n"
+        "\nNote: Models can be prefixed with 'openai/' or 'anthropic/' for LiteLLM format.\n"
+    )
+
+
+def _get_raw_model_name(model: str) -> str:
+    """Strip provider prefix from model name if present."""
+    for prefix in ("openai/", "anthropic/"):
+        if model.startswith(prefix):
+            return model[len(prefix):]
+    return model
+
+
+def _deduplicate_citations(citations: List[Dict[str, str]]) -> List[Dict[str, str]]:
+    """Remove duplicate citations by URL, preserving order."""
+    seen_urls = set()
+    unique = []
+    for citation in citations:
+        url = citation.get("url", "")
+        if url and url not in seen_urls:
+            seen_urls.add(url)
+            unique.append(citation)
+    return unique
+
+
+def _format_citations(citations: List[Dict[str, str]]) -> str:
+    """Format a list of citations into a markdown string."""
+    unique_citations = _deduplicate_citations(citations)
+    if not unique_citations:
+        return ""
+
+    lines = ["\n\n---\n**Sources:**"]
+    for i, citation in enumerate(unique_citations, 1):
+        title = citation.get("title", "Untitled")
+        url = citation.get("url", "")
+        line = f"{i}. [{title}]({url})" if url else f"{i}. {title}"
+        lines.append(line)
+
+    return "\n".join(lines) + "\n"
+
+
+# Mock classes for litellm response format compatibility
+class _MockDelta:
+    def __init__(self, content: str):
+        self.content = content
+
+
+class _MockChoice:
+    def __init__(self, content: str):
+        self.delta = _MockDelta(content)
+
+
+class _MockChunk:
+    def __init__(self, content: str):
+        self.choices = [_MockChoice(content)]
+
+
+def _create_chunk(content: str) -> _MockChunk:
+    """Create a mock chunk that matches litellm response format."""
+    return _MockChunk(content)
+
+
+def _extract_openai_citations(response) -> List[Dict[str, str]]:
+    """Extract citations from OpenAI Responses API response."""
+    citations = []
+    output = getattr(response, 'output', None)
+    if not output:
+        return citations
+
+    for output_item in output:
+        if getattr(output_item, 'type', None) != 'message':
+            continue
+        content = getattr(output_item, 'content', [])
+        for content_item in content:
+            annotations = getattr(content_item, 'annotations', [])
+            for annotation in annotations:
+                if getattr(annotation, 'type', None) == 'url_citation':
+                    citations.append({
+                        "title": getattr(annotation, 'title', 'Source'),
+                        "url": getattr(annotation, 'url', ''),
+                    })
+    return citations
+
+
+def _perform_openai_chat_completions_search(client, raw_model: str, query: str) -> Generator:
+    """Perform web search using Chat Completions API."""
+    response = client.chat.completions.create(
+        model=raw_model,
+        messages=[{"role": "user", "content": query}],
+        stream=True,
+    )
+    for chunk in response:
+        if chunk.choices and chunk.choices[0].delta.content:
+            yield _create_chunk(chunk.choices[0].delta.content)
+
+
+def _perform_openai_responses_api_search(client, raw_model: str, query: str) -> Generator:
+    """Perform web search using Responses API with web_search tool."""
+    response = client.responses.create(
+        model=raw_model,
+        tools=[{"type": "web_search"}],
+        input=query,
+    )
+
+    output_text = getattr(response, 'output_text', None)
+    if output_text:
+        yield _create_chunk(output_text)
+
+    citations = _extract_openai_citations(response)
+    citations_text = _format_citations(citations)
+    if citations_text:
+        yield _create_chunk(citations_text)
+
+
+def perform_openai_web_search(query: str, model: str) -> Generator:
+    """Perform web search using OpenAI's API."""
+    from openai import OpenAI
+
+    client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
+    raw_model = _get_raw_model_name(model)
+
+    if model in OPENAI_CHAT_COMPLETIONS_SEARCH_MODELS:
+        yield from _perform_openai_chat_completions_search(client, raw_model, query)
+    else:
+        yield from _perform_openai_responses_api_search(client, raw_model, query)
+
+
+def _extract_anthropic_text_citations(content_block) -> List[Dict[str, str]]:
+    """Extract citations from Anthropic text block."""
+    citations = []
+    block_citations = getattr(content_block, 'citations', None)
+    if not block_citations:
+        return citations
+
+    for citation in block_citations:
+        if hasattr(citation, 'url'):
+            citations.append({
+                "title": getattr(citation, 'title', 'Source'),
+                "url": citation.url,
+            })
+    return citations
+
+
+def _extract_anthropic_search_results(content_block) -> List[Dict[str, str]]:
+    """Extract citations from Anthropic web search tool result."""
+    citations = []
+    content = getattr(content_block, 'content', [])
+
+    for result in content:
+        if getattr(result, 'type', None) == "web_search_result":
+            citations.append({
+                "title": getattr(result, 'title', 'Source'),
+                "url": getattr(result, 'url', ''),
+            })
+    return citations
+
+
+def perform_anthropic_web_search(query: str, model: str) -> Generator:
+    """Perform web search using Anthropic's Messages API."""
+    import anthropic
+
+    client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+    raw_model = _get_raw_model_name(model)
+    citations = []
+
+    response = client.messages.create(
+        model=raw_model,
+        max_tokens=4096,
+        tools=[{"type": "web_search_20250305",
+                "name": "web_search", "max_uses": 5}],
+        messages=[{"role": "user", "content": query}],
+    )
+
+    for content_block in response.content:
+        if content_block.type == "text":
+            yield _create_chunk(content_block.text)
+            citations.extend(_extract_anthropic_text_citations(content_block))
+        elif content_block.type == "web_search_tool_result":
+            citations.extend(_extract_anthropic_search_results(content_block))
+
+    citations_text = _format_citations(citations)
+    if citations_text:
+        yield _create_chunk(citations_text)
+
+
+def perform_web_search_completion(query: str) -> Generator:
+    """Performs a web search using the appropriate provider based on default LLM."""
+    chat_instance = LLMSingleton.get_instance()
+    config_parameters = chat_instance.get_config_by_purpose("default")
+    model = config_parameters.get("model")
+
+    is_supported, provider = is_web_search_supported(model)
+
+    if not is_supported:
+        raise AraError(get_supported_models_message(model))
+
+    if provider == "openai":
+        yield from perform_openai_web_search(query, model)
+    elif provider == "anthropic":
+        yield from perform_anthropic_web_search(query, model)

ara_cli/commands/agent_run_command.py

@@ -0,0 +1,98 @@
+import argparse
+from ara_cli.commands.command import Command
+from ara_cli.error_handler import AraError
+
+
+class AgentRunCommand(Command):
+    def __init__(self, chat_instance, args):
+        self.chat_instance = chat_instance
+        self.args = args
+        self.parser = self._create_parser()
+
+    def _create_parser(self):
+        """Creates and configures the argument parser."""
+        parser = argparse.ArgumentParser(
+            prog="AGENT_RUN",
+            description="Run a binary agent.",
+            add_help=False,  # We handle help manually
+        )
+        parser.add_argument("agent_name", nargs="?",
+                            help="The name of the agent to run.")
+        parser.add_argument("-b", "--base-dir", dest="base_dir",
+                            help="Specify the base directory for the agent.")
+        parser.add_argument("-r", "--requirements", dest="requirements",
+                            action="append", help="Specify a requirements file or directory.")
+        parser.add_argument("-h", "--help", action="store_true",
+                            help="Show this help message.")
+        return parser
+
+    def _handle_help(self, arg_list):
+        """Handles the --help flag for the agent command."""
+        agent_name = next(
+            (arg for arg in arg_list if not arg.startswith('-')), None)
+
+        if agent_name:
+            try:
+                self.chat_instance.agent_manager.run_agent(
+                    agent_name, ["--help"])
+            except SystemExit:
+                pass  # Common with argparse's --help
+            except Exception:
+                print(f"Displaying built-in help for {agent_name}:\n")
+                self.parser.print_help()
+        else:
+            self.parser.print_help()
+        return True
+
+    def _prepare_agent_args(self, parsed_args, unknown_args):
+        """Prepares the arguments to be passed to the agent."""
+        agent_args = list(unknown_args)
+
+        if parsed_args.base_dir:
+            print(f"Using base directory: {parsed_args.base_dir}")
+            agent_args.extend(["--base-dir", parsed_args.base_dir])
+
+        if parsed_args.requirements:
+            print(f"Requirements Paths ({len(parsed_args.requirements)}):")
+            for req_path in parsed_args.requirements:
+                print(f"  - {req_path}")
+                agent_args.extend(["--requirements", req_path])
+
+        # elif self.chat_instance.source_artefact_path:
+        #     print(
+        #         f"INFO: Automatically passing source artefact to agent: {self.chat_instance.source_artefact_path}")
+        #     agent_args.insert(0, self.chat_instance.source_artefact_path)
+        #     agent_args.insert(0, "-r")
+
+        return agent_args
+
+    def _run_agent(self, parsed_args, unknown_args):
+        """Runs the agent with the prepared arguments."""
+        if not parsed_args.agent_name:
+            raise AraError("Usage: AGENT_RUN <agent_name> [args...]")
+
+        agent_name = parsed_args.agent_name
+        agent_args = self._prepare_agent_args(parsed_args, unknown_args)
+
+        self.chat_instance.agent_manager.run_agent(agent_name, agent_args)
+
+    def execute(self):
+        """
+        Parses arguments and runs a binary agent, handling help requests and errors.
+        """
+        try:
+            arg_list = self.args.split()
+            if "-h" in arg_list or "--help" in arg_list:
+                self._handle_help(arg_list)
+                return
+
+            parsed_args, unknown_args = self.parser.parse_known_args(arg_list)
+            self._run_agent(parsed_args, unknown_args)
+
+        except SystemExit:
+            # Argparse may exit, which is fine.
+            pass
+        except AraError as e:
+            raise e
+        except Exception as e:
+            print(f"An unexpected error occurred: {e}")