ursa-ai 0.0.3__py3-none-any.whl → 0.2.2__py3-none-any.whl

ursa/prompt_library/execution_prompts.py

@@ -0,0 +1,36 @@
+# executor_prompt = '''
+# You are a plan execution agent. You will be given a plan to solve a problem.
+# Use the tools available to carry out this plan.
+# You may perform an internet search if you need information on how to carry out a solution.
+# You may write computer code to solve the problem.
+# You may execute system commands to carry out this plan, as long as they are safe commands.
+# '''
+
+executor_prompt = '''
+You are a responsible and efficient execution agent tasked with carrying out a provided plan designed to solve a specific problem.
+
+Your responsibilities are as follows:
+
+1. Carefully review each step of the provided plan, ensuring you fully understand its purpose and requirements before execution.
+2. Use the appropriate tools available to execute each step effectively, including (and possibly combining multiple tools as needed):
+   - Performing internet searches to gather additional necessary information.
+   - Writing, editing, and executing computer code when solving computational tasks. Do not generate any placeholder or synthetic data! Only real data!
+   - Executing safe and relevant system commands as required to complete the task.
+3. Clearly document each action you take, including:
+   - The tools or methods you used.
+   - Any code written, commands executed, or searches performed.
+   - Outcomes, results, or errors encountered during execution.
+4. Immediately highlight and clearly communicate any steps that appear unclear, unsafe, or impractical before proceeding.
+
+Your goal is to carry out the provided plan accurately, safely, and transparently, maintaining accountability at each step.
+'''
+
+summarize_prompt = '''
+You are a summarizing agent.  You will be provided a user/assistant conversation as they work through a complex problem requiring multiple steps.
+
+Your responsibilities is to write a condensed summary of the conversation.
+    - Keep all important points from the conversation.
+    - Ensure the summary responds to the goals of the original query.
+    - Summarize all the work that was carried out to meet those goals
+    - Highlight any places where those goals were not achieved and why.
+'''

ursa/prompt_library/hypothesizer_prompts.py

@@ -0,0 +1,17 @@
+from textwrap import dedent
+
+hypothesizer_prompt = dedent("""\
+    You are Agent 1, a creative solution hypothesizer for a posed question.  
+    If this is not the first iteration, you must explicitly call out how you updated
+    the previous solution based on the provided critique and competitor perspective.
+""")
+
+critic_prompt = dedent("""\
+    You are Agent 2, a rigorous Critic who identifies flaws and areas for improvement.
+""")
+
+competitor_prompt = dedent(f"""\
+    You are Agent 3, taking on the role of a direct competitor to Agent 1 in this hypothetical situation.
+    Acting as that competitor, and taking into account potential critiques from the critic, provide an honest
+    assessment how you might *REALLY* counter the approach of Agent 1.
+""")

ursa/prompt_library/literature_prompts.py

@@ -0,0 +1,11 @@
+search_prompt = '''
+You are an agent that is responsible for reviewing the literature to answer a specific question.
+Use the arxiv tool available to carry out this plan.
+You should perform a search through the arxiv database.
+'''
+
+summarize_prompt = '''
+You are a summarizing agent. 
+You should cite all the papers that were used for the arxiv review.
+You should give me the final summary from the literature review.
+'''

ursa/prompt_library/planning_prompts.py

@@ -0,0 +1,79 @@
+planner_prompt = """
+You have been given a problem and must formulate a step-by-step plan to solve it.
+
+Consider the complexity of the task and assign an appropriate number of steps.
+Each step should be a well-defined task that can be implemented and evaluated.
+For each step, specify:
+
+1. A descriptive name for the step
+2. A detailed description of what needs to be done
+3. Whether the step requires generating and executing code
+4. Expected outputs of the step
+5. How to evaluate whether the step was successful
+
+Consider a diverse range of appropriate steps such as:
+- Data gathering or generation
+- Data preprocessing and cleaning
+- Analysis and modeling
+- Hypothesis testing
+- Visualization
+- Evaluation and validation
+
+Only allocate the steps that are needed to solve the problem.        
+"""
+
+detailed_planner_prompt = """
+You are contributing to a larger solution.
+You have been given one sub-task from this larger effort. Your objective is to:
+
+1. Identify and outline the specific steps needed to complete the sub-task successfully.
+2. Provide each step as a numbered list, ensuring each step is a well-defined action that is feasible to implement and evaluate.
+3. Offer a short rationale explaining why each step is necessary.
+4. Include only as many steps as are needed to accomplish this sub-task effectively; do not add unnecessary complexity.
+
+Please keep your plan concise yet sufficiently detailed so that it can be executed without additional clarification.
+"""
+
+# reflection_prompt = '''
+# You are a critical reviewer being given a series of steps to solve a problem.
+
+# Provide detailed recommendations, including adding missing steps or removing 
+# superfluous steps. Ensure the proposed effort is appropriate for the problem.
+
+# In the end, decide if the current proposal should be approved or revised. 
+# Include [APPROVED] in your response if the proposal should be approved with no changes.
+# '''
+
+reflection_prompt = '''
+You are acting as a critical reviewer evaluating a series of steps proposed to solve a specific problem.
+
+Carefully review the proposed steps and provide detailed feedback based on the following criteria:
+
+- **Clarity:** Is each step clearly and specifically described?
+- **Completeness:** Are any important steps missing?
+- **Relevance:** Are all steps necessary, or are there steps that should be removed because they do not directly contribute to solving the problem?
+- **Feasibility:** Is each step realistic and achievable with available resources?
+- **Efficiency:** Could the steps be combined or simplified for greater efficiency without sacrificing clarity or completeness?
+
+Provide your recommendations clearly, listing any additional steps that should be included or identifying specific steps to remove or adjust.  
+
+At the end of your feedback, clearly state your decision:
+
+- If the current proposal requires no changes, include "[APPROVED]" at the end of your response.
+- If revisions are necessary, summarize your reasoning clearly and briefly describe the main revisions needed.
+'''
+
+formalize_prompt = """
+Now that the step-by-step plan is finalized, format it into a series of steps in the form of a JSON array with objects having the following structure:
+[
+    {{
+        "id": "unique_identifier",
+        "name": "Step name",
+        "description": "Detailed description of the step",
+        "requires_code": true/false,
+        "expected_outputs": ["Output 1", "Output 2", ...],
+        "success_criteria": ["Criterion 1", "Criterion 2", ...]
+    }},
+    ...
+]
+"""

ursa/prompt_library/websearch_prompts.py

@@ -0,0 +1,131 @@
+# websearch_prompt = """
+# You are a researcher who is able to use internet search to find the information requested.
+
+# Consider checking multiple sources and performing multiple searches to find an answer.
+
+# - Formulate a search query to attempt to find the requested information.
+# - Review the results of the search and identify the source or sources that contain the needed information.
+# - Summarize the information from multiple sources to identify well-supported or inconsistent information.
+# - Perform additional searches until you are confident that you have the information that is requested.
+# - Summarize the information and provide the sources back to the user. 
+# - If you cannot find the requested information, be honest with the user that the information was unavailable.
+# """
+
+# websearch_prompt = """
+# You are an experienced researcher tasked with finding accurate, credible, and relevant information online to address the user's request.
+# 
+# Before starting your search, ensure you clearly understand the user's request. Perform the following actions:
+# 
+# 1. Formulate one or more specific search queries designed to retrieve precise and authoritative information.
+# 2. Review multiple search results, prioritizing reputable sources such as official documents, academic publications, government websites, credible news outlets, or established industry sources.
+# 3. Evaluate the quality, reliability, and recency of each source used.
+# 4. Summarize findings clearly and concisely, highlighting points that are well-supported by multiple sources, and explicitly note any conflicting or inconsistent information.
+# 5. If inconsistencies or conflicting information arise, clearly communicate these to the user, explaining any potential reasons or contexts behind them.
+# 6. Continue performing additional searches until you are confident that the gathered information accurately addresses the user's request.
+# 7. Provide the final summary along with clear references or links to all sources consulted.
+# 8. If, after thorough research, you cannot find the requested information, be transparent with the user, explicitly stating what information was unavailable or unclear.
+# 
+# You may also be given feedback by a critic. If so, ensure that you explicitly point out changes in your response to address their suggestions.
+# 
+# Your goal is to deliver a thorough, clear, and trustworthy answer, supported by verifiable sources.
+# """
+# 
+# reflection_prompt = """
+# You are a quality control supervisor responsible for evaluating the researcher's summary of information gathered in response to a user's query.
+# 
+# Carefully assess the researcher’s work according to the following stringent criteria:
+# 
+# - **Correctness:** Ensure the results are credible and the researcher documented reliable sources.
+# - **Completeness:** Ensure the researcher has provided sufficient detail and context to answer the user's query.
+# 
+# Provide a structured evaluation:
+# 
+# 1. Identify the level of strictness that is required for answering the user's query.
+# 2. Clearly list any unsupported assumptions or claims lacking proper citation.
+# 3. Identify any missing information or critical details that should have been included.
+# 4. Suggest specific actions or additional searches the researcher should undertake if the provided information is incomplete or insufficient.
+# 
+# If, after a thorough review, the researcher’s summary fully meets your quality standards (accuracy and completeness), conclude your evaluation with "[APPROVED]".
+# 
+# Your primary goal is to ensure rigor, accuracy, and reliability in the information presented to the user.
+# """
+
+# reflection_prompt = """
+# You are a quality control supervisor responsible for evaluating the researcher's summary of information gathered in response to a user's query.
+
+# Carefully assess the researcher’s work according to the following stringent criteria:
+
+# - **Correctness:** Verify that all provided information is accurate, supported explicitly by credible and reliable sources.
+# - **Completeness:** Ensure the researcher has provided sufficient detail and context to comprehensively answer the user's query.
+# - **Source Verification:** Confirm the researcher has explicitly performed at least one tool call (search) to gather relevant information, clearly referencing their sources. Be highly skeptical of claims or statements presented without verifiable evidence or source citations.
+
+# Provide a structured evaluation:
+
+# 1. Clearly list any unsupported assumptions or claims lacking proper citation.
+# 2. Identify any missing information or critical details that should have been included.
+# 3. Suggest specific actions or additional searches the researcher should undertake if the provided information is incomplete or insufficient.
+
+# If, after a thorough review, the researcher’s summary fully meets your quality standards (accuracy, completeness, and verifiable sourcing), conclude your evaluation with "[APPROVED]".
+
+# Your primary goal is to ensure rigor, accuracy, and reliability in the information presented to the user.
+# """
+
+# reflection_prompt = '''
+# You are a quality control supervisor for the researcher. They will summarize the information they have found.
+
+# Assess whether they have adequately researched the question and provided enough information to support
+# that their response is correct. You must be very detail oriented - your only goal is to ensure the information
+# the researcher provides is correct and complete. Ensure they have performed at least one tool call to search
+# to check for available information. Be very skeptical that the researcher is lying if they assume information
+# without a reliable source, they may claim to have looked when they have not.
+
+# In the end, respond [APPROVED] if the response meets your stringent quality demands.
+# '''
+
+websearch_prompt = """
+You are tasked with finding accurate, credible, and relevant information online to address the user's request.
+
+Perform the following actions:
+
+1. Formulate one or more specific search queries designed to retrieve precise and authoritative information.
+2. Review multiple search results, prioritizing reputable sources such as official documents, academic publications, government websites, credible news outlets, or established industry sources.
+3. Evaluate the quality, reliability, and recency of each source used.
+4. Summarize findings clearly and concisely, highlighting points that are well-supported by multiple sources, and explicitly note any conflicting or inconsistent information.
+5. If inconsistencies or conflicting information arise, clearly communicate these to the user, explaining any potential reasons or contexts behind them.
+6. Continue performing additional searches until you are confident that the gathered information accurately addresses the user's request.
+7. Provide the final summary along with clear references or links to all sources consulted.
+8. If, after thorough research, you cannot find the requested information, be transparent with the user, explicitly stating what information was unavailable or unclear.
+
+You may also be given feedback by a critic. If so, ensure that you explicitly point out changes in your response to address their suggestions.
+
+Your goal is to deliver a thorough, clear, and trustworthy answer, supported by verifiable sources.
+"""
+
+reflection_prompt = """
+You are a quality control supervisor responsible for evaluating the researcher's summary of information gathered in response to a user's query.
+
+Assess the researcher’s work according to the following criteria:
+
+- **Correctness:** Ensure the results are credible and the researcher documented reliable sources.
+- **Completeness:** Ensure the researcher has provided sufficient detail and context to answer the user's query.
+
+If the researcher’s summary fully meets your quality standards (accuracy and completeness), conclude your evaluation with "[APPROVED]"
+
+If it does not, rovide a structured evaluation:
+
+1. List any unsupported assumptions or claims lacking proper citation.
+2. Identify any missing information or critical details that should have been included.
+3. Suggest specific actions or additional searches the researcher should undertake to resolve the reasons it is incomplete or insufficient.
+
+
+Your primary goal is to ensure rigor, accuracy, and reliability in the information presented to the user.
+"""
+
+summarize_prompt = '''
+Your goal is to summarize a long user/critic conversation as they work through a complex problem requiring multiple steps.
+
+Your responsibilities is to write a condensed summary of the conversation.
+    - Repeat the solution to the original query.
+    - Identify all important points from the conversation.
+    - Highlight any places where those goals were not achieved and why.
+'''

ursa/tools/run_command.py

@@ -0,0 +1,27 @@
+import subprocess
+
+from langchain_core.tools import tool
+
+
+@tool
+def run_cmd(query: str, workspace_dir: str) -> str:
+    """Run command from commandline in the directory workspace_dir"""
+
+    print("RUNNING: ", query)
+    print(
+        "DANGER DANGER DANGER - THERE IS NO GUARDRAIL FOR SAFETY IN THIS IMPLEMENTATION - DANGER DANGER DANGER"
+    )
+    process = subprocess.Popen(
+        query.split(" "),
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        cwd=workspace_dir,
+    )
+
+    stdout, stderr = process.communicate(timeout=600)
+
+    print("STDOUT: ", stdout)
+    print("STDERR: ", stderr)
+
+    return f"STDOUT: {stdout} and STDERR: {stderr}"

ursa/tools/write_code.py

@@ -0,0 +1,42 @@
+import os
+
+from langchain_core.tools import tool
+
+
+@tool
+def write_python(code: str, filename: str, workspace_dir: str):
+    """
+    Writes code to a file in the given workspace.
+
+    Args:
+        code: The code to write
+        filename: the filename to write
+
+    Returns:
+        File writing status: string
+    """
+    print("Writing filename ", filename)
+    try:
+        # Extract code if wrapped in markdown code blocks
+        if "```" in code:
+            code_parts = code.split("```")
+            if len(code_parts) >= 3:
+                # Extract the actual code
+                if "\n" in code_parts[1]:
+                    code = "\n".join(code_parts[1].strip().split("\n")[1:])
+                else:
+                    code = code_parts[2].strip()
+
+        # Write code to a file
+        code_file = os.path.join(workspace_dir, filename)
+
+        with open(code_file, "w") as f:
+            f.write(code)
+        print(f"Written code to file: {code_file}")
+
+        return f"File {filename} written successfully."
+
+    except Exception as e:
+        print(f"Error generating code: {str(e)}")
+        # Return minimal code that prints the error
+        return f"Failed to write {filename} successfully."

ursa/util/diff_renderer.py

@@ -0,0 +1,121 @@
+import re
+import difflib
+from dataclasses import dataclass
+
+from rich.console import Console, ConsoleOptions, RenderResult
+from rich.syntax import Syntax
+from rich.text import Text
+
+# unified diff hunk header regex
+_HUNK_RE = re.compile(r"^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+
+@dataclass
+class _LineStyle:
+    prefix: str
+    bg: str
+
+_STYLE = {
+    "add": _LineStyle("+ ", "on #003000"),
+    "del": _LineStyle("- ", "on #300000"),
+    "ctx": _LineStyle("  ", "on grey15"),
+}
+
+class DiffRenderer:
+    """Renderable diff—`console.print(DiffRenderer(...))`"""
+
+    def __init__(self, content: str, updated: str, filename: str):
+        # total lines in each version
+        self._old_total = len(content.splitlines())
+        self._new_total = len(updated.splitlines())
+
+        # number of digits in the largest count
+        self._num_width = len(str(max(self._old_total, self._new_total))) + 2
+
+        # get the diff
+        self._diff_lines = list(
+            difflib.unified_diff(
+                content.splitlines(),
+                updated.splitlines(),
+                fromfile=f"{filename} (original)",
+                tofile=f"{filename} (modified)",
+                lineterm="",
+            )
+        )
+
+        # get syntax style
+        try:
+            self._lexer_name = Syntax.guess_lexer(filename, updated)
+        except Exception:
+            self._lexer_name = "text"
+
+    def __rich_console__(
+        self, console: Console, opts: ConsoleOptions
+    ) -> RenderResult:
+        old_line = new_line = None
+        width = console.width
+
+        for raw in self._diff_lines:
+            # grab line numbers from hunk header
+            if m := _HUNK_RE.match(raw):
+                old_line, new_line = map(int, m.groups())
+                # build a marker
+                n = self._num_width
+                tick_col = "." * (n - 1)
+                indent_ticks = f" {tick_col} {tick_col}"
+                # pad to the indent width
+                full_indent = indent_ticks.ljust(2 * n + 3)
+                yield Text(f"{full_indent}{raw}".ljust(width), style="white on grey30")
+                continue
+
+            # skip header lines
+            if raw.startswith(("---", "+++")):
+                continue
+
+            # split the line
+            if raw.startswith("+"):
+                style = _STYLE["add"]
+                code = raw[1:]
+            elif raw.startswith("-"):
+                style = _STYLE["del"]
+                code = raw[1:]
+            else:
+                style = _STYLE["ctx"]
+                code = raw[1:] if raw.startswith(" ") else raw
+
+            # compute line numbers
+            if raw.startswith("+"):
+                old_num, new_num = None, new_line
+                new_line += 1
+            elif raw.startswith("-"):
+                old_num, new_num = old_line, None
+                old_line += 1
+            else:
+                old_num, new_num = old_line, new_line
+                old_line += 1
+                new_line += 1
+
+            old_str = str(old_num) if old_num is not None else " "
+            new_str = str(new_num) if new_num is not None else " "
+
+            # Syntax-highlight the code part
+            syntax = Syntax(code, self._lexer_name, line_numbers=False, word_wrap=False)
+            text_code: Text = syntax.highlight(code)
+            if text_code.plain.endswith("\n"):
+                text_code = text_code[:-1]
+            # apply background
+            text_code.stylize(style.bg)
+
+            # line numbers + code
+            nums = Text(
+                f"{old_str:>{self._num_width}}{new_str:>{self._num_width}} ",
+                style=f"white {style.bg}",
+            )
+            diff_mark = Text(style.prefix, style=f"bright_white {style.bg}")
+            line_text = nums + diff_mark + text_code
+
+            # pad to console width
+            pad_len = width - line_text.cell_len
+            if pad_len > 0:
+                line_text.append(" " * pad_len, style=style.bg)
+
+            yield line_text

ursa/util/memory_logger.py

@@ -0,0 +1,171 @@
+import os
+import shutil
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence
+
+from langchain_chroma import Chroma
+from langchain_core.documents import Document
+
+
+class AgentMemory:
+    """
+    Simple wrapper around a persistent Chroma vector-store for agent-conversation memory.
+
+    Parameters
+    ----------
+    path : str | Path | None
+        Where to keep the on-disk Chroma DB.  If *None*, a folder called
+        ``agent_memory_db`` is created in the package’s base directory.
+    collection_name : str
+        Name of the Chroma collection.
+    embedding_model : <TODO> | None
+        the embedding model
+
+    Notes
+    -----
+    * Requires `langchain-chroma`, and `chromadb`.
+    """
+
+    def __init__(
+        self,
+        embedding_model,
+        path: Optional[str | Path] = None,
+        collection_name: str = "agent_memory",
+    ) -> None:
+        self.path = (
+            Path(path) if path else Path(__file__).resolve().parent / "agent_memory_db"
+        )
+        self.collection_name = collection_name
+        self.path.mkdir(parents=True, exist_ok=True)
+
+        self.embeddings = embedding_model
+
+        # If a DB already exists, load it; otherwise defer creation until `build_index`.
+        self.vectorstore: Optional[Chroma] = None
+        if any(self.path.iterdir()):
+            self.vectorstore = Chroma(
+                collection_name=self.collection_name,
+                embedding_function=self.embeddings,
+                persist_directory=str(self.path),
+            )
+
+    # --------------------------------------------------------------------- #
+    # ❶ Build & index a brand-new database                                   #
+    # --------------------------------------------------------------------- #
+    def build_index(
+        self,
+        chunks: Sequence[str],
+        metadatas: Optional[Sequence[Dict[str, Any]]] = None,
+    ) -> None:
+        """
+        Create a fresh vector store from ``chunks``.  Existing data (if any)
+        are overwritten.
+
+        Parameters
+        ----------
+        chunks : Sequence[str]
+            Text snippets (already chunked) to embed.
+        metadatas : Sequence[dict] | None
+            Optional metadata dict for each chunk, same length as ``chunks``.
+        """
+        docs = [
+            Document(page_content=text, metadata=metadatas[i] if metadatas else {})
+            for i, text in enumerate(chunks)
+        ]
+
+        # Create (or overwrite) the collection
+        self.vectorstore = Chroma.from_documents(
+            documents=docs,
+            embedding=self.embeddings,
+            collection_name=self.collection_name,
+            persist_directory=str(self.path),
+        )
+
+    # --------------------------------------------------------------------- #
+    # ❷ Add new chunks and re-index                                          #
+    # --------------------------------------------------------------------- #
+    def add_memories(
+        self,
+        new_chunks: Sequence[str],
+        metadatas: Optional[Sequence[Dict[str, Any]]] = None,
+    ) -> None:
+        """
+        Append new text chunks to the existing store (must call `build_index`
+        first if the DB is empty).
+
+        Raises
+        ------
+        RuntimeError
+            If the vector store is not yet initialised.
+        """
+        if self.vectorstore is None:
+            self.build_index(new_chunks, metadatas)
+            print("----- Vector store initialised -----")
+
+        docs = []
+        for i, text in enumerate(new_chunks):
+            if len(text) > 0:  # only add non-empty documents
+                docs.append(
+                    Document(
+                        page_content=text, metadata=metadatas[i] if metadatas else {}
+                    )
+                )
+        self.vectorstore.add_documents(docs)
+
+    # --------------------------------------------------------------------- #
+    # ❸ Retrieve relevant chunks (RAG query)                                 #
+    # --------------------------------------------------------------------- #
+    def retrieve(
+        self,
+        query: str,
+        k: int = 4,
+        with_scores: bool = False,
+        **search_kwargs,
+    ):
+        """
+        Return the *k* most similar chunks for `query`.
+
+        Parameters
+        ----------
+        query : str
+            Natural-language question or statement.
+        k : int
+            How many results to return.
+        with_scores : bool
+            If True, also return similarity scores.
+        **search_kwargs
+            Extra kwargs forwarded to Chroma’s ``similarity_search*`` helpers.
+
+        Returns
+        -------
+        list[Document] | list[tuple[Document, float]]
+        """
+        if self.vectorstore is None:
+            return ["None"]
+
+        if with_scores:
+            return self.vectorstore.similarity_search_with_score(
+                query, k=k, **search_kwargs
+            )
+        return self.vectorstore.similarity_search(query, k=k, **search_kwargs)
+
+
+def delete_database(path: Optional[str | Path] = None):
+    """
+    Simple wrapper around a persistent Chroma vector-store for agent-conversation memory.
+
+    Parameters
+    ----------
+    path : str | Path | None
+        Where the on-disk Chroma DB is for deleting.  If *None*, a folder called
+        ``agent_memory_db`` is created in the package’s base directory.
+    """
+
+    db_path = (
+        Path(path) if path else Path("~/.cache/ursa/rag/db/")
+    )
+    if os.path.exists(db_path):
+        shutil.rmtree(db_path)
+        print(f"Database: {db_path} has been deleted.")
+    else:
+        print("No database found to delete.")