flock-core 0.1.2__py3-none-any.whl → 0.2.2__py3-none-any.whl

flock/core/tools/basic_tools.py

@@ -1,98 +1,296 @@
-import os
-
-import httpx
-from markdownify import markdownify as md
-from tavily import TavilyClient
-
-
-def web_search_tavily(query: str):
-    client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))
-    try:
-        response = client.search(query, include_answer=True)  # type: ignore
-        return response
-    except Exception:
-        raise
-
-
-def get_web_content_as_markdown(url: str):
-    try:
-        response = httpx.get(url)
-        response.raise_for_status()
-        markdown = md(response.text)
-        return markdown
-    except Exception:
-        raise
-
-
-def evaluate_math(expression: str) -> float:
-    import dspy
-
-    try:
-        result = dspy.PythonInterpreter({}).execute(expression)
-        return result
-    except Exception:
-        raise
-
-
-def code_eval(python_code: str) -> float:
-    import dspy
-
-    try:
-        result = dspy.PythonInterpreter({}).execute(python_code)
-        return result
-    except Exception:
-        raise
-
-
-def get_current_time() -> str:
-    import datetime
-
-    time = datetime.datetime.now().isoformat()
-    return time
-
-
-def count_words(text: str) -> int:
-    count = len(text.split())
-    return count
-
-
-def extract_urls(text: str) -> list[str]:
-    import re
-
-    url_pattern = r"https?://(?:[-\w.]|(?:%[\da-fA-F]{2}))+"
-    urls = re.findall(url_pattern, text)
-    return urls
-
-
-def extract_numbers(text: str) -> list[float]:
-    import re
-
-    numbers = [float(x) for x in re.findall(r"-?\d*\.?\d+", text)]
-    return numbers
-
-
-def json_parse_safe(text: str) -> dict:
-    import json
-
-    try:
-        result = json.loads(text)
-        return result
-    except Exception:
-        return {}
-
-
-def save_to_file(content: str, filename: str):
-    try:
-        with open(filename, "w") as f:
-            f.write(content)
-    except Exception:
-        raise
-
-
-def read_from_file(filename: str) -> str:
-    try:
-        with open(filename) as f:
-            content = f.read()
-        return content
-    except Exception:
-        raise
+"""This module contains basic agentic tools for performing various tasks."""
+
+import importlib
+import os
+
+from flock.core.logging.trace_and_logged import traced_and_logged
+
+
+@traced_and_logged
+def web_search_tavily(query: str):
+    """Performs a web search using the Tavily client.
+
+    This function checks if the optional 'tavily' dependency is installed. If so,
+    it creates a TavilyClient using the API key from the environment variable
+    'TAVILY_API_KEY' and performs a search with the provided query. The search response
+    is returned if successful.
+
+    Parameters:
+        query (str): The search query string.
+
+    Returns:
+        Any: The search response obtained from the Tavily client.
+
+    Raises:
+        ImportError: If the 'tavily' dependency is not installed.
+        Exception: Re-raises any exceptions encountered during the search.
+    """
+    if importlib.util.find_spec("tavily") is not None:
+        from tavily import TavilyClient
+
+        client = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))
+        try:
+            response = client.search(query, include_answer=True)  # type: ignore
+            return response
+        except Exception:
+            raise
+    else:
+        raise ImportError(
+            "Optional tool dependencies not installed. Install with 'pip install flock-core[tools]'."
+        )
+
+
+@traced_and_logged
+def get_web_content_as_markdown(url: str):
+    """Fetches web content from a URL and converts it to Markdown.
+
+    This function uses the 'httpx' library to retrieve the content of the provided URL.
+    It then converts the HTML content into Markdown using the 'markdownify' library.
+
+    Parameters:
+        url (str): The URL of the web page to fetch.
+
+    Returns:
+        str: The web page content converted into Markdown format.
+
+    Raises:
+        ImportError: If either 'httpx' or 'markdownify' dependencies are not installed.
+        Exception: Re-raises any exceptions encountered during the HTTP request or conversion.
+    """
+    if (
+        importlib.util.find_spec("httpx") is not None
+        and importlib.util.find_spec("markdownify") is not None
+    ):
+        import httpx
+        from markdownify import markdownify as md
+
+        try:
+            response = httpx.get(url)
+            response.raise_for_status()
+            markdown = md(response.text)
+            return markdown
+        except Exception:
+            raise
+    else:
+        raise ImportError(
+            "Optional tool dependencies not installed. Install with 'pip install flock-core[tools]'."
+        )
+
+
+@traced_and_logged
+def get_anything_as_markdown(url_or_file_path: str):
+    """Converts the content of a URL or file into Markdown format.
+
+    This function leverages the 'docling' library to convert various document types
+    (retrieved from a URL or a local file) into Markdown. It uses the DocumentConverter
+    from the 'docling.document_converter' module.
+
+    Parameters:
+        url_or_file_path (str): The URL or local file path of the document to convert.
+
+    Returns:
+        str: The converted document in Markdown format.
+
+    Raises:
+        ImportError: If the 'docling' dependency is not installed.
+        Exception: Re-raises any exceptions encountered during the document conversion.
+    """
+    if importlib.util.find_spec("docling") is not None:
+        from docling.document_converter import DocumentConverter
+
+        try:
+            converter = DocumentConverter()
+            result = converter.convert(url_or_file_path)
+            markdown = result.document.export_to_markdown()
+            return markdown
+        except Exception:
+            raise
+    else:
+        raise ImportError(
+            "Optional tool dependencies not installed. Install with 'pip install flock-core[all-tools]'."
+        )
+
+
+@traced_and_logged
+def evaluate_math(expression: str) -> float:
+    """Evaluates a mathematical expression using the dspy interpreter.
+
+    This function uses the 'dspy' library's PythonInterpreter to evaluate the provided
+    mathematical expression.
+
+    Parameters:
+        expression (str): A string containing the mathematical expression to evaluate.
+
+    Returns:
+        float: The result of the evaluated expression.
+
+    Raises:
+        Exception: Re-raises any exceptions encountered during the evaluation.
+    """
+    import dspy
+
+    try:
+        result = dspy.PythonInterpreter({}).execute(expression)
+        return result
+    except Exception:
+        raise
+
+
+@traced_and_logged
+def code_eval(python_code: str) -> float:
+    """Executes Python code using the dspy interpreter.
+
+    This function takes a string of Python code, executes it using the 'dspy' PythonInterpreter,
+    and returns the result.
+
+    Parameters:
+        python_code (str): A string containing Python code to execute.
+
+    Returns:
+        float: The result of the executed code.
+
+    Raises:
+        Exception: Re-raises any exceptions encountered during code execution.
+    """
+    import dspy
+
+    try:
+        result = dspy.PythonInterpreter({}).execute(python_code)
+        return result
+    except Exception:
+        raise
+
+
+@traced_and_logged
+def get_current_time() -> str:
+    """Retrieves the current time in ISO 8601 format.
+
+    Returns:
+        str: The current date and time as an ISO 8601 formatted string.
+    """
+    import datetime
+
+    time = datetime.datetime.now().isoformat()
+    return time
+
+
+@traced_and_logged
+def count_words(text: str) -> int:
+    """Counts the number of words in the provided text.
+
+    This function splits the input text by whitespace and returns the count of resulting words.
+
+    Parameters:
+        text (str): The text in which to count words.
+
+    Returns:
+        int: The number of words in the text.
+    """
+    count = len(text.split())
+    return count
+
+
+@traced_and_logged
+def extract_urls(text: str) -> list[str]:
+    """Extracts all URLs from the given text.
+
+    This function uses a regular expression to find all substrings that match the typical
+    URL pattern (starting with http or https).
+
+    Parameters:
+        text (str): The text from which to extract URLs.
+
+    Returns:
+        list[str]: A list of URLs found in the text.
+    """
+    import re
+
+    url_pattern = r"https?://(?:[-\w.]|(?:%[\da-fA-F]{2}))+"
+    urls = re.findall(url_pattern, text)
+    return urls
+
+
+@traced_and_logged
+def extract_numbers(text: str) -> list[float]:
+    """Extracts all numerical values from the provided text.
+
+    This function uses a regular expression to find substrings that represent integers or decimals,
+    converts them to floats, and returns them as a list.
+
+    Parameters:
+        text (str): The text from which to extract numerical values.
+
+    Returns:
+        list[float]: A list of numbers (as floats) found in the text.
+    """
+    import re
+
+    numbers = [float(x) for x in re.findall(r"-?\d*\.?\d+", text)]
+    return numbers
+
+
+@traced_and_logged
+def json_parse_safe(text: str) -> dict:
+    """Safely parses a JSON string into a dictionary.
+
+    This function attempts to load a JSON object from the given text. If parsing fails,
+    it returns an empty dictionary instead of raising an exception.
+
+    Parameters:
+        text (str): The JSON-formatted string to parse.
+
+    Returns:
+        dict: The parsed JSON object as a dictionary, or an empty dictionary if parsing fails.
+    """
+    import json
+
+    try:
+        result = json.loads(text)
+        return result
+    except Exception:
+        return {}
+
+
+@traced_and_logged
+def save_to_file(content: str, filename: str):
+    """Saves the given content to a file.
+
+    This function writes the provided content to a file specified by the filename.
+    If the file cannot be written, an exception is raised.
+
+    Parameters:
+        content (str): The content to be saved.
+        filename (str): The path to the file where the content will be saved.
+
+    Raises:
+        Exception: Re-raises any exceptions encountered during the file write operation.
+    """
+    try:
+        with open(filename, "w") as f:
+            f.write(content)
+    except Exception:
+        raise
+
+
+@traced_and_logged
+def read_from_file(filename: str) -> str:
+    """Reads and returns the content of a file.
+
+    This function opens the specified file, reads its content, and returns it as a string.
+    If the file cannot be read, an exception is raised.
+
+    Parameters:
+        filename (str): The path to the file to be read.
+
+    Returns:
+        str: The content of the file.
+
+    Raises:
+        Exception: Re-raises any exceptions encountered during the file read operation.
+    """
+    try:
+        with open(filename) as f:
+            content = f.read()
+        return content
+    except Exception:
+        raise

flock/core/tools/dev_tools/github.py

@@ -0,0 +1,190 @@
+"""This module provides tools for interacting with GitHub repositories."""
+
+import base64
+import os
+
+import httpx
+
+from flock.core.logging.trace_and_logged import traced_and_logged
+
+
+@traced_and_logged
+def create_user_stories_as_github_issue(title: str, body: str) -> str:
+    """Create a new GitHub issue representing a user story.
+
+    This function creates an issue in a GitHub repository using the specified title and body.
+    The title is used as the issue title, and the body should contain the full user story
+    description along with a formatted list of acceptance criteria. The following
+    environment variables must be set for this function to work correctly:
+
+      - GITHUB_PAT: Personal Access Token for GitHub API authentication.
+      - GITHUB_REPO: Repository identifier in the format "owner/repo".
+
+    Parameters:
+        title (str): The title for the GitHub issue (user story).
+        body (str): The detailed description including acceptance criteria.
+
+    Returns:
+        str: A message indicating whether the issue was created successfully or not.
+    """
+    github_pat = os.getenv("GITHUB_PAT")
+    github_repo = os.getenv("GITHUB_REPO")
+
+    url = f"https://api.github.com/repos/{github_repo}/issues"
+    headers = {
+        "Authorization": f"Bearer {github_pat}",
+        "Accept": "application/vnd.github+json",
+    }
+    issue_title = title
+    issue_body = body
+
+    payload = {"title": issue_title, "body": issue_body}
+    response = httpx.post(url, json=payload, headers=headers)
+
+    if response.status_code == 201:
+        return "Issue created successfully."
+    else:
+        return "Failed to create issue. Please try again later."
+
+
+@traced_and_logged
+def upload_readme(content: str):
+    """Upload or update the README.md file in a GitHub repository.
+
+    This function uses the GitHub API to either create a new README.md file or update an
+    existing one in the specified repository. It encodes the provided content to base64 before
+    sending it via the API. The function requires the following environment variables to be set:
+
+      - GITHUB_USERNAME: Your GitHub username.
+      - GITHUB_REPO: The name of the repository.
+      - GITHUB_PAT: Your GitHub Personal Access Token for authentication.
+
+    Parameters:
+        content (str): The text content to be written into the README.md file.
+
+    Raises:
+        ValueError: If any of the required environment variables are missing.
+    """
+    GITHUB_USERNAME = os.getenv("GITHUB_USERNAME")
+    REPO_NAME = os.getenv("GITHUB_REPO")
+    GITHUB_TOKEN = os.getenv("GITHUB_PAT")
+
+    if not GITHUB_USERNAME or not REPO_NAME or not GITHUB_TOKEN:
+        raise ValueError(
+            "Missing environment variables: GITHUB_USERNAME, GITHUB_REPO, or GITHUB_PAT"
+        )
+
+    GITHUB_API_URL = f"https://api.github.com/repos/{GITHUB_USERNAME}/{REPO_NAME}/contents/README.md"
+
+    encoded_content = base64.b64encode(content.encode()).decode()
+
+    with httpx.Client() as client:
+        response = client.get(
+            GITHUB_API_URL,
+            headers={
+                "Authorization": f"Bearer {GITHUB_TOKEN}",
+                "Accept": "application/vnd.github.v3+json",
+            },
+        )
+
+        data = response.json()
+        sha = data.get("sha", None)
+
+        payload = {
+            "message": "Updating README.md",
+            "content": encoded_content,
+            "branch": "main",
+        }
+
+        if sha:
+            payload["sha"] = sha
+
+        response = client.put(
+            GITHUB_API_URL,
+            json=payload,
+            headers={
+                "Authorization": f"Bearer {GITHUB_TOKEN}",
+                "Accept": "application/vnd.github.v3+json",
+            },
+        )
+
+        if response.status_code in [200, 201]:
+            print("README.md successfully uploaded/updated!")
+        else:
+            print("Failed to upload README.md:", response.json())
+
+
+@traced_and_logged
+def create_files(file_paths) -> str:
+    """Create multiple files in a GitHub repository with a predefined content.
+
+    This function iterates over a list of file paths (relative to the repository root) and creates
+    each file in the specified GitHub repository with the content "#created by flock". For each file,
+    it checks whether the file already exists; if it does, that file is skipped. The function
+    uses the following environment variables for authentication and repository information:
+
+      - GITHUB_USERNAME: Your GitHub username.
+      - GITHUB_REPO: The name of the repository.
+      - GITHUB_PAT: Your GitHub Personal Access Token for authentication.
+
+    Parameters:
+        file_paths (list of str): A list of file paths (relative to the repository root) to be created.
+
+    Returns:
+        str: A message indicating whether the files were created successfully or if there was a failure.
+    """
+    try:
+        GITHUB_USERNAME = os.getenv("GITHUB_USERNAME")
+        REPO_NAME = os.getenv("GITHUB_REPO")
+        GITHUB_TOKEN = os.getenv("GITHUB_PAT")
+
+        if not GITHUB_USERNAME or not REPO_NAME or not GITHUB_TOKEN:
+            raise ValueError(
+                "Missing environment variables: GITHUB_USERNAME, GITHUB_REPO, or GITHUB_PAT"
+            )
+
+        encoded_content = base64.b64encode(b"#created by flock").decode()
+
+        with httpx.Client() as client:
+            for file_path in file_paths:
+                GITHUB_API_URL = f"https://api.github.com/repos/{GITHUB_USERNAME}/{REPO_NAME}/contents/{file_path}"
+
+                response = client.get(
+                    GITHUB_API_URL,
+                    headers={
+                        "Authorization": f"token {GITHUB_TOKEN}",
+                        "Accept": "application/vnd.github.v3+json",
+                    },
+                )
+
+                data = response.json()
+                sha = data.get("sha", None)
+
+                payload = {
+                    "message": f"Creating {file_path}",
+                    "content": encoded_content,
+                    "branch": "main",
+                }
+
+                if sha:
+                    print(f"Skipping {file_path}, file already exists.")
+                    continue
+
+                response = client.put(
+                    GITHUB_API_URL,
+                    json=payload,
+                    headers={
+                        "Authorization": f"token {GITHUB_TOKEN}",
+                        "Accept": "application/vnd.github.v3+json",
+                    },
+                )
+
+                if response.status_code in [200, 201]:
+                    print(f"{file_path} successfully created!")
+                else:
+                    print(f"Failed to create {file_path}:", response.json())
+
+        return "Files created successfully."
+
+    except Exception:
+        return "Failed to create file. Please try again later."

flock/core/util/cli_helper.py

@@ -0,0 +1,25 @@
+from rich.console import Console
+from rich.syntax import Text
+
+console = Console()
+
+
+def display_banner():
+    """Display the Flock banner."""
+    banner_text = Text(
+        """
+        🦆   🐓   🐤    🦆
+    ╭━━━━━━━━━━━━━━━━━━━━━━━━╮
+🐓  │ ▒█▀▀▀ █░░ █▀▀█ █▀▀ █░█ │  🐧
+    │ ▒█▀▀▀ █░░ █░░█ █░░ █▀▄ │
+🐧  │ ▒█░░░ ▀▀▀ ▀▀▀▀ ▀▀▀ ▀░▀ │  🐓
+    ╰━━━━━━━━━━━━━━━━━━━━━━━━╯
+        🦆     🐤    🐧     🐓
+""",
+        justify="center",
+        style="bold orange3",
+    )
+    console.print(banner_text)
+    console.print(
+        f"[bold]v0.2.1[/] - [bold]white duck GmbH[/] - [cyan]https://whiteduck.de[/]\n"
+    )