flock-core 0.4.0b46__py3-none-any.whl → 0.4.0b49__py3-none-any.whl

flock/tools/__init__.py

@@ -0,0 +1,188 @@
+from .azure_tools import (
+    azure_search_create_index,
+    azure_search_create_vector_index,
+    azure_search_delete_documents,
+    azure_search_get_document,
+    azure_search_get_index_statistics,
+    azure_search_initialize_clients,
+    azure_search_list_indexes,
+    azure_search_query,
+    azure_search_upload_documents,
+    azure_storage_create_container,
+    azure_storage_delete_blob,
+    azure_storage_delete_container,
+    azure_storage_download_blob_to_bytes,
+    azure_storage_download_blob_to_file,
+    azure_storage_download_blob_to_text,
+    azure_storage_get_blob_properties,
+    azure_storage_list_blobs,
+    azure_storage_list_containers,
+    azure_storage_upload_blob_bytes,
+    azure_storage_upload_blob_from_file,
+    azure_storage_upload_blob_text,
+)
+from .code_tools import code_code_eval, code_evaluate_math
+from .file_tools import (
+    file_get_anything_as_markdown,
+    file_json_parse_safe,
+    file_json_search,
+    file_read_from_file,
+    file_save_to_file,
+)
+from .github_tools import (
+    github_create_files,
+    github_create_user_stories_as_github_issue,
+    github_upload_readme,
+)
+from .markdown_tools import (
+    markdown_extract_code_blocks,
+    markdown_extract_links,
+    markdown_extract_tables,
+    markdown_split_by_headers,
+    markdown_to_plain_text,
+)
+from .text_tools import (
+    text_calculate_hash,
+    text_chunking_for_embedding,
+    text_clean_text,
+    text_count_tokens,
+    text_count_tokens_estimate,
+    text_count_words,
+    text_detect_language,
+    text_extract_json_from_text,
+    text_extract_keywords,
+    text_extract_numbers,
+    text_extract_urls,
+    text_format_chat_history,
+    text_format_table_from_dicts,
+    text_recursive_splitter,
+    text_split_by_characters,
+    text_split_by_sentences,
+    text_split_by_separator,
+    text_split_by_tokens,
+    text_split_code_by_functions,
+    text_tiktoken_split,
+    text_truncate_to_token_limit,
+)
+from .web_tools import (
+    web_content_as_markdown,
+    web_search_bing,
+    web_search_duckduckgo,
+    web_search_tavily,
+)
+from .zendesk_tools import (
+    zendesk_get_article_by_id,
+    zendesk_get_articles,
+    zendesk_get_comments_by_ticket_id,
+    zendesk_get_ticket_by_id,
+    zendesk_get_tickets,
+    zendesk_search_articles,
+)
+
+storage_tools = [
+    azure_storage_list_containers,
+    azure_storage_create_container,
+    azure_storage_delete_container,
+    azure_storage_list_blobs,
+    azure_storage_upload_blob_text,
+    azure_storage_upload_blob_bytes,
+    azure_storage_upload_blob_from_file,
+    azure_storage_download_blob_to_text,
+    azure_storage_download_blob_to_bytes,
+    azure_storage_download_blob_to_file,
+    azure_storage_delete_blob,
+    azure_storage_get_blob_properties,
+]
+
+azure_search_tools = [
+    azure_search_initialize_clients,
+    azure_search_create_index,
+    azure_search_upload_documents,
+    azure_search_query,
+    azure_search_get_document,
+    azure_search_delete_documents,
+    azure_search_list_indexes,
+    azure_search_get_index_statistics,
+    azure_search_create_vector_index,
+]
+
+file_tools_collection = [
+    file_get_anything_as_markdown,
+    file_save_to_file,
+    file_read_from_file,
+    file_json_parse_safe,
+    file_json_search,
+]
+
+code_tools_collection = [code_evaluate_math, code_code_eval]
+
+web_tools_collection = [
+    web_content_as_markdown,
+    web_search_bing,
+    web_search_duckduckgo,
+    web_search_tavily,
+]
+
+github_tools_collection = [
+    github_create_user_stories_as_github_issue,
+    github_upload_readme,
+    github_create_files,
+]
+
+llm_processing_tools = [
+    text_split_by_sentences,
+    text_split_by_characters,
+    text_split_by_tokens,
+    text_split_by_separator,
+    text_recursive_splitter,
+    text_chunking_for_embedding,
+    text_split_code_by_functions,
+    text_count_tokens,
+    text_count_tokens_estimate,
+    text_truncate_to_token_limit,
+    text_extract_keywords,
+    text_clean_text,
+    text_format_chat_history,
+    text_extract_json_from_text,
+    text_calculate_hash,
+    text_format_table_from_dicts,
+    text_detect_language,
+    text_tiktoken_split,
+    text_count_words,
+    text_extract_urls,
+    text_extract_numbers,
+]
+
+markdown_processing_tools = [
+    markdown_split_by_headers,
+    markdown_extract_code_blocks,
+    markdown_extract_links,
+    markdown_extract_tables,
+    markdown_to_plain_text,
+]
+
+zendesk_tools_collection = [
+    zendesk_get_tickets,
+    zendesk_get_ticket_by_id,
+    zendesk_get_comments_by_ticket_id,
+    zendesk_get_article_by_id,
+    zendesk_get_articles,
+    zendesk_search_articles,
+]
+
+__all__ = [
+    "azure_search_tools",
+    "code_tools_collection",
+    "file_tools_collection",
+    "github_tools_collection",
+    "llm_processing_tools",
+    "markdown_processing_tools",
+    "storage_tools",
+    "web_tools_collection",
+    "zendesk_tools_collection",
+]
+
+# If there was existing content in __init__.py, this approach might overwrite it.
+# A safer approach if __init__.py might exist and have other critical initializations
+# would be to read it first, then append/modify.
+# For now, assuming a fresh creation or simple __init__.py.

flock/{core/tools → tools}/azure_tools.py

@@ -16,6 +16,10 @@ from azure.search.documents.indexes.models import (
     VectorSearchProfile,
 )
 from azure.search.documents.models import VectorizedQuery
+from azure.storage.blob import (
+    BlobServiceClient,
+    ContentSettings,
+)
 
 from flock.core.logging.trace_and_logged import traced_and_logged
 
@@ -495,3 +499,283 @@ def azure_search_create_vector_index(
         }
     except Exception as e:
         return {"error": str(e), "created": False}
+
+
+# --- Azure Blob Storage Tools ---
+
+def _get_blob_service_client(conn_string_env_var: str) -> BlobServiceClient:
+    """Helper function to get BlobServiceClient using a connection string from an environment variable."""
+    actual_connection_string = os.environ.get(conn_string_env_var)
+    if not actual_connection_string:
+        raise ValueError(f"Environment variable '{conn_string_env_var}' for Azure Storage connection string is not set or is empty.")
+    return BlobServiceClient.from_connection_string(actual_connection_string)
+
+
+@traced_and_logged
+def azure_storage_list_containers(conn_string_env_var: str) -> list[str]:
+    """Lists all containers in the Azure Storage account.
+
+    Args:
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+
+    Returns:
+        A list of container names.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    containers = blob_service_client.list_containers()
+    return [container.name for container in containers]
+
+
+@traced_and_logged
+def azure_storage_create_container(container_name: str, conn_string_env_var: str) -> dict[str, Any]:
+    """Creates a new container in the Azure Storage account.
+
+    Args:
+        container_name: The name of the container to create.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+
+    Returns:
+        A dictionary with creation status.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    try:
+        blob_service_client.create_container(container_name)
+        return {"container_name": container_name, "created": True, "message": f"Container '{container_name}' created successfully."}
+    except Exception as e:
+        return {"container_name": container_name, "created": False, "error": str(e)}
+
+
+@traced_and_logged
+def azure_storage_delete_container(container_name: str, conn_string_env_var: str) -> dict[str, Any]:
+    """Deletes an existing container from the Azure Storage account.
+
+    Args:
+        container_name: The name of the container to delete.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+
+    Returns:
+        A dictionary with deletion status.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    try:
+        blob_service_client.delete_container(container_name)
+        return {"container_name": container_name, "deleted": True, "message": f"Container '{container_name}' deleted successfully."}
+    except Exception as e:
+        return {"container_name": container_name, "deleted": False, "error": str(e)}
+
+
+@traced_and_logged
+def azure_storage_list_blobs(container_name: str, conn_string_env_var: str) -> list[str]:
+    """Lists all blobs in a specified container.
+
+    Args:
+        container_name: The name of the container.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+
+    Returns:
+        A list of blob names.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    container_client = blob_service_client.get_container_client(container_name)
+    blob_list = container_client.list_blobs()
+    return [blob.name for blob in blob_list]
+
+
+@traced_and_logged
+def azure_storage_upload_blob_text(container_name: str, blob_name: str, text_content: str, conn_string_env_var: str, overwrite: bool = True) -> dict[str, Any]:
+    """Uploads text content as a blob to the specified container.
+
+    Args:
+        container_name: The name of the container.
+        blob_name: The name of the blob to create.
+        text_content: The string content to upload.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+        overwrite: Whether to overwrite the blob if it already exists. Defaults to True.
+
+    Returns:
+        A dictionary with upload status.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
+    try:
+        content_settings = ContentSettings(content_type='text/plain')
+        blob_client.upload_blob(text_content.encode('utf-8'), overwrite=overwrite, content_settings=content_settings)
+        return {"container_name": container_name, "blob_name": blob_name, "uploaded": True, "message": "Text content uploaded successfully."}
+    except Exception as e:
+        return {"container_name": container_name, "blob_name": blob_name, "uploaded": False, "error": str(e)}
+
+
+@traced_and_logged
+def azure_storage_upload_blob_bytes(container_name: str, blob_name: str, bytes_content: bytes, conn_string_env_var: str, overwrite: bool = True) -> dict[str, Any]:
+    """Uploads bytes content as a blob to the specified container.
+
+    Args:
+        container_name: The name of the container.
+        blob_name: The name of the blob to create.
+        bytes_content: The bytes content to upload.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+        overwrite: Whether to overwrite the blob if it already exists. Defaults to True.
+
+    Returns:
+        A dictionary with upload status.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
+    try:
+        content_settings = ContentSettings(content_type='application/octet-stream')
+        blob_client.upload_blob(bytes_content, overwrite=overwrite, content_settings=content_settings)
+        return {"container_name": container_name, "blob_name": blob_name, "uploaded": True, "message": "Bytes content uploaded successfully."}
+    except Exception as e:
+        return {"container_name": container_name, "blob_name": blob_name, "uploaded": False, "error": str(e)}
+
+
+@traced_and_logged
+def azure_storage_upload_blob_from_file(container_name: str, blob_name: str, file_path: str, conn_string_env_var: str, overwrite: bool = True) -> dict[str, Any]:
+    """Uploads a local file to a blob in the specified container.
+
+    Args:
+        container_name: The name of the container.
+        blob_name: The name of the blob to create.
+        file_path: The local path to the file to upload.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+        overwrite: Whether to overwrite the blob if it already exists. Defaults to True.
+
+    Returns:
+        A dictionary with upload status.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
+    try:
+        with open(file_path, "rb") as data:
+            blob_client.upload_blob(data, overwrite=overwrite)
+        return {"container_name": container_name, "blob_name": blob_name, "file_path": file_path, "uploaded": True, "message": "File uploaded successfully."}
+    except FileNotFoundError:
+        return {"container_name": container_name, "blob_name": blob_name, "file_path": file_path, "uploaded": False, "error": "File not found."}
+    except Exception as e:
+        return {"container_name": container_name, "blob_name": blob_name, "file_path": file_path, "uploaded": False, "error": str(e)}
+
+
+@traced_and_logged
+def azure_storage_download_blob_to_text(container_name: str, blob_name: str, conn_string_env_var: str) -> str:
+    """Downloads a blob's content as text.
+
+    Args:
+        container_name: The name of the container.
+        blob_name: The name of the blob to download.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+
+    Returns:
+        The blob content as a string.
+
+    Raises:
+        Exception: If download fails or blob is not text.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
+    try:
+        download_stream = blob_client.download_blob()
+        return download_stream.readall().decode('utf-8')
+    except Exception as e:
+        raise Exception(f"Failed to download or decode blob '{blob_name}' from container '{container_name}': {e!s}")
+
+
+@traced_and_logged
+def azure_storage_download_blob_to_bytes(container_name: str, blob_name: str, conn_string_env_var: str) -> bytes:
+    """Downloads a blob's content as bytes.
+
+    Args:
+        container_name: The name of the container.
+        blob_name: The name of the blob to download.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+
+    Returns:
+        The blob content as bytes.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
+    download_stream = blob_client.download_blob()
+    return download_stream.readall()
+
+
+@traced_and_logged
+def azure_storage_download_blob_to_file(container_name: str, blob_name: str, file_path: str, conn_string_env_var: str, overwrite: bool = True) -> dict[str, Any]:
+    """Downloads a blob to a local file.
+
+    Args:
+        container_name: The name of the container.
+        blob_name: The name of the blob to download.
+        file_path: The local path to save the downloaded file.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+        overwrite: Whether to overwrite the local file if it exists. Defaults to True.
+
+    Returns:
+        A dictionary with download status.
+    """
+    if not overwrite and os.path.exists(file_path):
+        return {"container_name": container_name, "blob_name": blob_name, "file_path": file_path, "downloaded": False, "error": "File exists and overwrite is False."}
+
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
+    try:
+        with open(file_path, "wb") as download_file:
+            download_stream = blob_client.download_blob()
+            download_file.write(download_stream.readall())
+        return {"container_name": container_name, "blob_name": blob_name, "file_path": file_path, "downloaded": True, "message": "File downloaded successfully."}
+    except Exception as e:
+        return {"container_name": container_name, "blob_name": blob_name, "file_path": file_path, "downloaded": False, "error": str(e)}
+
+
+@traced_and_logged
+def azure_storage_delete_blob(container_name: str, blob_name: str, conn_string_env_var: str) -> dict[str, Any]:
+    """Deletes a specified blob from a container.
+
+    Args:
+        container_name: The name of the container.
+        blob_name: The name of the blob to delete.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+
+    Returns:
+        A dictionary with deletion status.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
+    try:
+        blob_client.delete_blob()
+        return {"container_name": container_name, "blob_name": blob_name, "deleted": True, "message": "Blob deleted successfully."}
+    except Exception as e:
+        return {"container_name": container_name, "blob_name": blob_name, "deleted": False, "error": str(e)}
+
+
+@traced_and_logged
+def azure_storage_get_blob_properties(container_name: str, blob_name: str, conn_string_env_var: str) -> dict[str, Any]:
+    """Retrieves properties of a specified blob.
+
+    Args:
+        container_name: The name of the container.
+        blob_name: The name of the blob.
+        conn_string_env_var: The name of the environment variable holding the Azure Storage connection string.
+
+    Returns:
+        A dictionary containing blob properties.
+    """
+    blob_service_client = _get_blob_service_client(conn_string_env_var)
+    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
+    try:
+        properties = blob_client.get_blob_properties()
+        return {
+            "name": properties.name,
+            "container": properties.container,
+            "size": properties.size,
+            "content_type": properties.content_settings.content_type,
+            "last_modified": properties.last_modified.isoformat() if properties.last_modified else None,
+            "etag": properties.etag,
+            # Add more properties as needed
+        }
+    except Exception as e:
+        return {"container_name": container_name, "blob_name": blob_name, "error": str(e)}
+
+# Potential future tools:
+# - azure_storage_set_blob_metadata
+# - azure_storage_get_blob_metadata
+# - azure_storage_generate_sas_token_blob
+# - azure_storage_copy_blob

flock/tools/code_tools.py

@@ -0,0 +1,56 @@
+from flock.core.interpreter.python_interpreter import PythonInterpreter
+from flock.core.logging.trace_and_logged import traced_and_logged
+
+
+@traced_and_logged
+def code_evaluate_math(expression: str) -> float:
+    try:
+        result = PythonInterpreter(
+            {},
+            [
+                "os",
+                "math",
+                "random",
+                "datetime",
+                "time",
+                "string",
+                "collections",
+                "itertools",
+                "functools",
+                "typing",
+                "enum",
+                "json",
+                "ast",
+            ],
+            verbose=True,
+        ).execute(expression)
+        return result
+    except Exception:
+        raise
+
+
+@traced_and_logged
+def code_code_eval(python_code: str) -> str:
+    try:
+        result = PythonInterpreter(
+            {},
+            [
+                "os",
+                "math",
+                "random",
+                "datetime",
+                "time",
+                "string",
+                "collections",
+                "itertools",
+                "functools",
+                "typing",
+                "enum",
+                "json",
+                "ast",
+            ],
+            verbose=True,
+        ).execute(python_code)
+        return result
+    except Exception:
+        raise

flock/tools/file_tools.py

@@ -0,0 +1,140 @@
+import importlib
+import json
+from typing import Any
+
+from flock.core.logging.trace_and_logged import traced_and_logged
+
+
+@traced_and_logged
+def file_get_anything_as_markdown(url_or_file_path: str):
+    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[file-tools]'."
+        )
+
+
+@traced_and_logged
+def file_save_to_file(content: str, filename: str):
+    try:
+        with open(filename, "w") as f:
+            f.write(content)
+    except Exception:
+        raise
+
+
+@traced_and_logged
+def file_read_from_file(filename: str) -> str:
+    with open(filename, encoding="utf-8") as file:
+        return file.read()
+
+
+@traced_and_logged
+def file_json_parse_safe(text: str) -> dict:
+    try:
+        result = json.loads(text)
+        return result
+    except Exception:
+        return {}
+
+
+@traced_and_logged
+def file_json_search(
+    json_file_path: str, search_query: str, case_sensitive: bool = False
+) -> list:
+    """Search a JSON file for objects containing the specified search query.
+
+    Args:
+        json_file_path (str): Path to the JSON file to search
+        search_query (str): Text to search for within the JSON objects
+        case_sensitive (bool, optional): Whether to perform a case-sensitive search. Defaults to False.
+
+    Returns:
+        list: List of JSON objects (as dicts) that contain the search query
+
+    Example:
+        >>> matching_tickets = file_json_search("tickets.json", "error 404")
+        >>> print(
+        ...     f"Found {len(matching_tickets)} tickets mentioning '404 error'"
+        ... )
+    """
+    try:
+        # Read the JSON file
+        file_content = file_read_from_file(json_file_path)
+
+        # Parse the JSON content
+        json_data = file_json_parse_safe(file_content)
+
+        # Convert search query to lowercase if case-insensitive search
+        if not case_sensitive:
+            search_query = search_query.lower()
+
+        results = []
+
+        # Determine if the JSON root is an object or array
+        if isinstance(json_data, dict):
+            # Handle case where root is a dictionary object
+            for key, value in json_data.items():
+                if isinstance(value, list):
+                    # If this key contains a list of objects, search within them
+                    matching_items = _search_in_list(
+                        value, search_query, case_sensitive
+                    )
+                    results.extend(matching_items)
+                elif _contains_text(value, search_query, case_sensitive):
+                    # The entire object matches
+                    results.append(json_data)
+                    break
+        elif isinstance(json_data, list):
+            # Handle case where root is an array
+            matching_items = _search_in_list(
+                json_data, search_query, case_sensitive
+            )
+            results.extend(matching_items)
+
+        return results
+
+    except Exception as e:
+        return [{"error": f"Error searching JSON file: {e!s}"}]
+
+
+def _search_in_list(
+    items: list, search_query: str, case_sensitive: bool
+) -> list:
+    """Helper function to search for text in a list of items."""
+    matching_items = []
+    for item in items:
+        if _contains_text(item, search_query, case_sensitive):
+            matching_items.append(item)
+    return matching_items
+
+
+def _contains_text(obj: Any, search_query: str, case_sensitive: bool) -> bool:
+    """Recursively check if an object contains the search query in any of its string values."""
+    if isinstance(obj, str):
+        # For string values, check if they contain the search query
+        if case_sensitive:
+            return search_query in obj
+        else:
+            return search_query in obj.lower()
+    elif isinstance(obj, dict):
+        # For dictionaries, check each value
+        for value in obj.values():
+            if _contains_text(value, search_query, case_sensitive):
+                return True
+    elif isinstance(obj, list):
+        # For lists, check each item
+        for item in obj:
+            if _contains_text(item, search_query, case_sensitive):
+                return True
+    # For other types (numbers, booleans, None), return False
+    return False