basic-open-agent-tools 0.1.0__py3-none-any.whl

basic_open_agent_tools/__init__.py

@@ -0,0 +1,39 @@
+"""Basic Open Agent Tools.
+
+An open foundational toolkit providing essential components for building AI agents 
+with minimal dependencies for local (non-HTTP/API) actions.
+"""
+
+__version__ = "0.1.0"
+
+# Modular structure
+from . import file_system
+
+# Future modules (placeholder imports for when modules are implemented)
+# from . import text
+# from . import system
+# from . import network
+# from . import data
+# from . import crypto
+# from . import utilities
+
+# Common infrastructure
+from . import exceptions
+from . import types
+
+__all__ = [
+    # Modular structure
+    "file_system",
+    
+    # Future modules (uncomment when implemented)
+    # "text", 
+    # "system",
+    # "network",
+    # "data",
+    # "crypto",
+    # "utilities",
+    
+    # Common infrastructure
+    "exceptions",
+    "types",
+]

basic_open_agent_tools/crypto/TODO.md

@@ -0,0 +1,60 @@
+# Cryptographic Tools TODO
+
+## Overview
+Hashing, encoding, and basic cryptographic utilities (no encryption/decryption).
+
+## Planned Modules
+
+### High Priority
+- [ ] **Hashing** (`hashing.py`)
+  - File content hashing (MD5, SHA1, SHA256, SHA512)
+  - String hashing utilities
+  - Hash verification and comparison
+  - Checksum generation and validation
+  - Hash-based file integrity checking
+  - Bulk file hashing operations
+
+- [ ] **Encoding** (`encoding.py`)
+  - Base64 encoding/decoding
+  - URL-safe base64 operations
+  - Hexadecimal encoding/decoding
+  - URL encoding/decoding
+  - HTML entity encoding/decoding
+  - Percent encoding utilities
+
+### Medium Priority
+- [ ] **Utilities** (`utilities.py`)
+  - Random string generation
+  - UUID generation and validation
+  - Token generation (non-cryptographic)
+  - Data fingerprinting
+  - Simple obfuscation (not security)
+
+- [ ] **Validation** (`validation.py`)
+  - Hash format validation
+  - Checksum verification
+  - Integrity checking utilities
+  - Format validation for encoded data
+
+### Low Priority
+- [ ] **File Integrity** (`integrity.py`)
+  - File signature verification
+  - Batch integrity checking
+  - Integrity report generation
+  - File corruption detection
+
+## Important Notes
+- **NO ENCRYPTION/DECRYPTION** - This violates the project's security principles
+- Focus on data integrity and encoding only
+- Use only well-established, standard algorithms
+- Provide secure defaults
+- Clear documentation about security limitations
+
+## Design Considerations
+- Use standard library implementations where possible
+- Clear separation between secure and non-secure operations
+- Consistent error handling
+- Performance considerations for large files
+- Cross-platform compatibility
+- Clear documentation of security properties
+- Warning messages for deprecated hash algorithms

basic_open_agent_tools/crypto/__init__.py

@@ -0,0 +1,6 @@
+"""Cryptographic tools for AI agents.
+
+This module is not yet implemented. See TODO.md for planned functionality.
+"""
+
+__all__ = []  # No functions available yet

basic_open_agent_tools/data/TODO.md

@@ -0,0 +1,69 @@
+# Data Tools TODO
+
+## Overview
+Data structure utilities, validation, and serialization tools for AI agents.
+
+## Planned Modules
+
+### High Priority
+- [ ] **Data Structures** (`structures.py`)
+  - Dictionary manipulation utilities
+  - List processing helpers
+  - Data flattening and unflattening
+  - Nested data structure navigation
+  - Data merging and comparison
+  - Safe data access patterns
+
+- [ ] **Validation** (`validation.py`)
+  - Schema validation utilities
+  - Data type checking
+  - Range and constraint validation
+  - Required field validation
+  - Custom validation patterns
+  - Error aggregation and reporting
+
+- [ ] **Serialization** (`serialization.py`)
+  - JSON serialization with error handling
+  - Pickle utilities (with security considerations)
+  - Custom object serialization
+  - Data format conversion
+  - Safe deserialization patterns
+
+### Medium Priority
+- [ ] **Transformation** (`transform.py`)
+  - Data mapping and transformation
+  - Field renaming and restructuring
+  - Data type conversion
+  - Batch data processing
+  - Data cleaning utilities
+  - Duplicate detection and removal
+
+- [ ] **Query** (`query.py`)
+  - Simple data querying (like JSONPath)
+  - Data filtering utilities
+  - Search and find operations
+  - Data aggregation helpers
+  - Sorting and grouping utilities
+
+### Low Priority
+- [ ] **Caching** (`caching.py`)
+  - Simple in-memory caching
+  - LRU cache implementations
+  - Cache expiration handling
+  - Persistent cache utilities
+  - Cache statistics and monitoring
+
+- [ ] **Streaming** (`streaming.py`)
+  - Large data processing utilities
+  - Streaming data processors
+  - Batch processing helpers
+  - Memory-efficient data handling
+
+## Design Considerations
+- Memory efficiency for large datasets
+- Type safety and validation
+- Immutable data operations where possible
+- Clear error messages and handling
+- Performance considerations for bulk operations
+- Security awareness for deserialization
+- Consistent API design across modules

basic_open_agent_tools/data/__init__.py

@@ -0,0 +1,6 @@
+"""Data tools for AI agents.
+
+This module is not yet implemented. See TODO.md for planned functionality.
+"""
+
+__all__ = []  # No functions available yet

basic_open_agent_tools/exceptions.py

@@ -0,0 +1,11 @@
+"""Common exceptions for basic-open-agent-tools."""
+
+
+class BasicAgentToolsError(Exception):
+    """Base exception for all basic-open-agent-tools errors."""
+    pass
+
+
+class FileSystemError(BasicAgentToolsError):
+    """Exception for file system operations."""
+    pass

basic_open_agent_tools/file_system/TODO.md

@@ -0,0 +1,58 @@
+# File System Tools TODO
+
+## Current Status
+- ✅ Basic file operations (read, write, append) - implemented in `operations.py`
+- ✅ Directory operations (create, list, delete) - implemented in `operations.py`
+- ✅ File metadata and information - implemented in `info.py`
+- ✅ Directory tree functionality - implemented in `tree.py`
+- ✅ Path validation utilities - implemented in `validation.py`
+
+## Completed Tasks
+- ✅ Moved functionality to modular structure (`operations.py`, `info.py`, `tree.py`, `validation.py`)
+- ✅ Created proper `__init__.py` with organized exports
+- ✅ Added enhanced functionality (directory tree with depth control)
+
+## Future Enhancements
+
+### High Priority
+- [ ] **File Watching/Monitoring** (`watch.py`)
+  - Monitor file/directory changes
+  - Event-based file system notifications
+  - Polling-based monitoring for compatibility
+
+- [ ] **File Permissions** (`permissions.py`)
+  - Cross-platform permission management
+  - Permission checking and validation
+  - Safe permission modification
+
+### Medium Priority
+- [ ] **Advanced Operations** (`operations.py` extensions)
+  - Atomic file operations
+  - Temporary file management
+  - File locking mechanisms
+  - Bulk operations (batch copy, move, delete)
+
+- [ ] **Path Utilities** (`paths.py`)
+  - Path normalization and validation
+  - Relative/absolute path conversion
+  - Path pattern matching
+  - Cross-platform path handling
+
+### Low Priority
+- [ ] **File Comparison** (`compare.py`)
+  - File content comparison
+  - Directory structure comparison
+  - Checksums and integrity verification
+
+- [ ] **Archive Operations** (`archives.py`)
+  - ZIP file creation/extraction
+  - TAR file operations
+  - Directory compression
+
+## Design Considerations
+- Maintain cross-platform compatibility (Windows, macOS, Linux)
+- Use pathlib for modern path handling
+- Consistent error handling with custom exceptions
+- Type hints for all functions
+- Comprehensive docstrings and examples
+- Security considerations for file operations

basic_open_agent_tools/file_system/__init__.py

@@ -0,0 +1,73 @@
+"""File system tools for agent operations.
+
+This module provides comprehensive file and directory operations organized into logical submodules:
+
+- operations: Core file/directory operations (read, write, create, delete, copy, move)
+- info: File information and existence checking
+- tree: Directory tree listing functionality  
+- validation: Path validation utilities
+
+All functions are also available directly from this module for convenience.
+"""
+
+# Import all functions from submodules
+from .operations import (
+    read_file_to_string,
+    write_file_from_string,
+    append_to_file,
+    list_directory_contents,
+    create_directory,
+    delete_file,
+    delete_directory,
+    move_file,
+    copy_file,
+)
+
+from .info import (
+    get_file_info,
+    file_exists,
+    directory_exists,
+    get_file_size,
+    is_empty_directory,
+)
+
+from .tree import (
+    list_all_directory_contents,
+    generate_directory_tree,
+)
+
+from .validation import (
+    validate_path,
+    validate_file_content,
+)
+
+# Re-export all functions at module level for convenience
+__all__ = [
+    # File operations
+    "read_file_to_string",
+    "write_file_from_string", 
+    "append_to_file",
+    
+    # Directory operations
+    "list_directory_contents",
+    "create_directory",
+    "delete_file",
+    "delete_directory",
+    "move_file",
+    "copy_file",
+    
+    # Information and checking
+    "get_file_info",
+    "file_exists",
+    "directory_exists", 
+    "get_file_size",
+    "is_empty_directory",
+    
+    # Tree operations
+    "list_all_directory_contents",
+    "generate_directory_tree",
+    
+    # Validation utilities
+    "validate_path",
+    "validate_file_content",
+]

basic_open_agent_tools/file_system/info.py

@@ -0,0 +1,118 @@
+"""File and directory information utilities."""
+
+from typing import Dict, Union
+from ..exceptions import FileSystemError
+from .validation import validate_path
+
+
+def get_file_info(file_path: str) -> Dict[str, Union[str, int, float, bool]]:
+    """Get file or directory information.
+
+    Args:
+        file_path: Path to the file or directory
+
+    Returns:
+        Dictionary with file info: size, modified_time, is_file, is_directory, etc.
+
+    Raises:
+        FileSystemError: If path doesn't exist or info can't be retrieved
+    """
+    path = validate_path(file_path, "get info")
+    
+    if not path.exists():
+        raise FileSystemError(f"Path not found: {path}")
+    
+    try:
+        stat = path.stat()
+        return {
+            "name": path.name,
+            "size": stat.st_size,
+            "modified_time": stat.st_mtime,
+            "is_file": path.is_file(),
+            "is_directory": path.is_dir(),
+            "is_symlink": path.is_symlink(),
+            "absolute_path": str(path),
+            "parent": str(path.parent),
+            "suffix": path.suffix,
+            "permissions": oct(stat.st_mode)[-3:]
+        }
+    except OSError as e:
+        raise FileSystemError(f"Failed to get info for {path}: {e}")
+
+
+def file_exists(file_path: str) -> bool:
+    """Check if a file exists.
+
+    Args:
+        file_path: Path to check
+
+    Returns:
+        True if file exists, False otherwise
+    """
+    try:
+        path = validate_path(file_path, "check file existence")
+        return path.is_file()
+    except FileSystemError:
+        return False
+
+
+def directory_exists(directory_path: str) -> bool:
+    """Check if a directory exists.
+
+    Args:
+        directory_path: Path to check
+
+    Returns:
+        True if directory exists, False otherwise
+    """
+    try:
+        path = validate_path(directory_path, "check directory existence")
+        return path.is_dir()
+    except FileSystemError:
+        return False
+
+
+def get_file_size(file_path: str) -> int:
+    """Get file size in bytes.
+
+    Args:
+        file_path: Path to the file
+
+    Returns:
+        File size in bytes
+
+    Raises:
+        FileSystemError: If file doesn't exist or size can't be retrieved
+    """
+    path = validate_path(file_path, "get file size")
+    
+    if not path.is_file():
+        raise FileSystemError(f"File not found: {path}")
+    
+    try:
+        return path.stat().st_size
+    except OSError as e:
+        raise FileSystemError(f"Failed to get size for {path}: {e}")
+
+
+def is_empty_directory(directory_path: str) -> bool:
+    """Check if a directory is empty.
+
+    Args:
+        directory_path: Path to the directory
+
+    Returns:
+        True if directory is empty, False otherwise
+
+    Raises:
+        FileSystemError: If directory doesn't exist or can't be read
+    """
+    path = validate_path(directory_path, "check empty directory")
+    
+    if not path.is_dir():
+        raise FileSystemError(f"Directory not found: {path}")
+    
+    try:
+        return not any(path.iterdir())
+    except OSError as e:
+        raise FileSystemError(f"Failed to check if directory is empty {path}: {e}")

basic_open_agent_tools/file_system/operations.py

@@ -0,0 +1,232 @@
+"""Core file and directory operations."""
+
+import shutil
+from typing import List
+from ..exceptions import FileSystemError
+from .validation import validate_path, validate_file_content
+
+
+def read_file_to_string(file_path: str) -> str:
+    """Load string from a text file.
+
+    Args:
+        file_path: Path to the text file
+
+    Returns:
+        The file content as a string with leading/trailing whitespace stripped
+
+    Raises:
+        FileSystemError: If file doesn't exist or can't be read
+    """
+    path = validate_path(file_path, "read")
+    
+    if not path.is_file():
+        raise FileSystemError(f"File not found: {path}")
+    
+    try:
+        return path.read_text(encoding='utf-8').strip()
+    except (OSError, UnicodeDecodeError) as e:
+        raise FileSystemError(f"Failed to read file {path}: {e}")
+
+
+def write_file_from_string(file_path: str, content: str) -> bool:
+    """Write string content to a text file.
+
+    Args:
+        file_path: Path to the output file
+        content: String content to write
+
+    Returns:
+        True if successful
+
+    Raises:
+        FileSystemError: If write operation fails
+    """
+    validate_file_content(content, "write")
+    path = validate_path(file_path, "write")
+    
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding='utf-8')
+        return True
+    except OSError as e:
+        raise FileSystemError(f"Failed to write file {path}: {e}")
+
+
+def append_to_file(file_path: str, content: str) -> bool:
+    """Append string content to a text file.
+
+    Args:
+        file_path: Path to the file
+        content: String content to append
+
+    Returns:
+        True if successful
+
+    Raises:
+        FileSystemError: If append operation fails
+    """
+    validate_file_content(content, "append")
+    path = validate_path(file_path, "append")
+    
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open('a', encoding='utf-8') as file:
+            file.write(content)
+        return True
+    except OSError as e:
+        raise FileSystemError(f"Failed to append to file {path}: {e}")
+
+
+def list_directory_contents(directory_path: str, include_hidden: bool = False) -> List[str]:
+    """List contents of a directory.
+
+    Args:
+        directory_path: Path to the directory
+        include_hidden: Whether to include hidden files/directories
+
+    Returns:
+        Sorted list of file and directory names
+
+    Raises:
+        FileSystemError: If directory doesn't exist or can't be read
+    """
+    path = validate_path(directory_path, "list directory")
+    
+    if not path.is_dir():
+        raise FileSystemError(f"Directory not found: {path}")
+    
+    try:
+        contents = [item.name for item in path.iterdir()]
+        if not include_hidden:
+            contents = [name for name in contents if not name.startswith('.')]
+        return sorted(contents)
+    except OSError as e:
+        raise FileSystemError(f"Failed to list directory {path}: {e}")
+
+
+def create_directory(directory_path: str) -> bool:
+    """Create a directory and any necessary parent directories.
+
+    Args:
+        directory_path: Path to the directory to create
+
+    Returns:
+        True if successful
+
+    Raises:
+        FileSystemError: If directory creation fails
+    """
+    path = validate_path(directory_path, "create directory")
+    
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        return True
+    except OSError as e:
+        raise FileSystemError(f"Failed to create directory {path}: {e}")
+
+
+def delete_file(file_path: str) -> bool:
+    """Delete a file.
+
+    Args:
+        file_path: Path to the file to delete
+
+    Returns:
+        True if successful (including if file doesn't exist)
+
+    Raises:
+        FileSystemError: If deletion fails
+    """
+    path = validate_path(file_path, "delete file")
+    
+    try:
+        path.unlink(missing_ok=True)
+        return True
+    except OSError as e:
+        raise FileSystemError(f"Failed to delete file {path}: {e}")
+
+
+def delete_directory(directory_path: str, recursive: bool = False) -> bool:
+    """Delete a directory.
+
+    Args:
+        directory_path: Path to the directory to delete
+        recursive: If True, delete directory and all contents recursively
+
+    Returns:
+        True if successful (including if directory doesn't exist)
+
+    Raises:
+        FileSystemError: If deletion fails
+    """
+    path = validate_path(directory_path, "delete directory")
+    
+    if not path.exists():
+        return True
+    
+    try:
+        if recursive:
+            shutil.rmtree(path)
+        else:
+            path.rmdir()  # Only works if directory is empty
+        return True
+    except OSError as e:
+        raise FileSystemError(f"Failed to delete directory {path}: {e}")
+
+
+def move_file(source_path: str, destination_path: str) -> bool:
+    """Move or rename a file or directory.
+
+    Args:
+        source_path: Current path of the file/directory
+        destination_path: New path for the file/directory
+
+    Returns:
+        True if successful
+
+    Raises:
+        FileSystemError: If move operation fails
+    """
+    src_path = validate_path(source_path, "move source")
+    dst_path = validate_path(destination_path, "move destination")
+    
+    if not src_path.exists():
+        raise FileSystemError(f"Source path not found: {src_path}")
+    
+    try:
+        dst_path.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(src_path), str(dst_path))
+        return True
+    except OSError as e:
+        raise FileSystemError(f"Failed to move {src_path} to {dst_path}: {e}")
+
+
+def copy_file(source_path: str, destination_path: str) -> bool:
+    """Copy a file or directory.
+
+    Args:
+        source_path: Path of the source file/directory
+        destination_path: Path for the copied file/directory
+
+    Returns:
+        True if successful
+
+    Raises:
+        FileSystemError: If copy operation fails
+    """
+    src_path = validate_path(source_path, "copy source")
+    dst_path = validate_path(destination_path, "copy destination")
+    
+    if not src_path.exists():
+        raise FileSystemError(f"Source path not found: {src_path}")
+    
+    try:
+        dst_path.parent.mkdir(parents=True, exist_ok=True)
+        if src_path.is_file():
+            shutil.copy2(str(src_path), str(dst_path))
+        else:
+            shutil.copytree(str(src_path), str(dst_path))
+        return True
+    except OSError as e:
+        raise FileSystemError(f"Failed to copy {src_path} to {dst_path}: {e}")

basic_open_agent_tools/file_system/tree.py

@@ -0,0 +1,135 @@
+"""Directory tree listing functionality."""
+
+from pathlib import Path
+from typing import List
+from ..exceptions import FileSystemError
+from .validation import validate_path
+
+
+def list_all_directory_contents(directory_path: str) -> str:
+    """Generate a tree of all contents in a directory and its subdirectories.
+
+    Args:
+        directory_path: Path to the root directory to list
+
+    Returns:
+        Tree-like string representation of directory contents
+
+    Raises:
+        FileSystemError: If directory doesn't exist or can't be read
+    """
+    path = validate_path(directory_path, "list all directory contents")
+    
+    if not path.is_dir():
+        raise FileSystemError(f"Directory not found: {path}")
+    
+    def _should_include(item_path: Path) -> bool:
+        """Determine if an item should be included (exclude hidden files)."""
+        return not item_path.name.startswith('.')
+    
+    def _generate_tree(current_path: Path, prefix: str = '', is_last: bool = True) -> List[str]:
+        """Recursively generate tree representation."""
+        tree_lines = []
+        
+        # Prepare prefix for current level
+        current_prefix = prefix + ('└── ' if is_last else '├── ')
+        next_prefix = prefix + ('    ' if is_last else '│   ')
+        
+        # Add current directory/file to tree
+        tree_lines.append(f"{current_prefix}{current_path.name}")
+        
+        # If it's a directory, explore its contents
+        if current_path.is_dir():
+            try:
+                # Get contents, filtering hidden files
+                contents = [
+                    item for item in sorted(current_path.iterdir()) 
+                    if _should_include(item)
+                ]
+                
+                # Recursively add subdirectories and files
+                for i, item in enumerate(contents):
+                    is_last_item = (i == len(contents) - 1)
+                    tree_lines.extend(
+                        _generate_tree(item, next_prefix, is_last_item)
+                    )
+            except OSError as e:
+                tree_lines.append(f"  [Error reading directory: {e}]")
+        
+        return tree_lines
+    
+    try:
+        # Generate tree-like representation
+        return '\n'.join(_generate_tree(path))
+    
+    except OSError as e:
+        raise FileSystemError(f"Failed to list directory contents {path}: {e}")
+
+
+def generate_directory_tree(directory_path: str, max_depth: int = None, include_hidden: bool = False) -> str:
+    """Generate a customizable directory tree.
+
+    Args:
+        directory_path: Path to the root directory to list
+        max_depth: Maximum depth to traverse (None for unlimited)
+        include_hidden: Whether to include hidden files/directories
+
+    Returns:
+        Tree-like string representation of directory contents
+
+    Raises:
+        FileSystemError: If directory doesn't exist or can't be read
+    """
+    path = validate_path(directory_path, "generate directory tree")
+    
+    if not path.is_dir():
+        raise FileSystemError(f"Directory not found: {path}")
+    
+    def _should_include(item_path: Path) -> bool:
+        """Determine if an item should be included."""
+        if not include_hidden and item_path.name.startswith('.'):
+            return False
+        return True
+    
+    def _generate_tree(current_path: Path, prefix: str = '', depth: int = 0, is_last: bool = True) -> List[str]:
+        """Recursively generate tree representation with depth control."""
+        tree_lines = []
+        
+        # Check depth limit
+        if max_depth is not None and depth > max_depth:
+            return tree_lines
+        
+        # Prepare prefix for current level
+        current_prefix = prefix + ('└── ' if is_last else '├── ')
+        next_prefix = prefix + ('    ' if is_last else '│   ')
+        
+        # Add current directory/file to tree
+        tree_lines.append(f"{current_prefix}{current_path.name}")
+        
+        # If it's a directory and we haven't reached max depth, explore its contents
+        if current_path.is_dir() and (max_depth is None or depth < max_depth):
+            try:
+                # Get contents, filtering based on include_hidden
+                contents = [
+                    item for item in sorted(current_path.iterdir()) 
+                    if _should_include(item)
+                ]
+                
+                # Recursively add subdirectories and files
+                for i, item in enumerate(contents):
+                    is_last_item = (i == len(contents) - 1)
+                    tree_lines.extend(
+                        _generate_tree(item, next_prefix, depth + 1, is_last_item)
+                    )
+            except OSError as e:
+                tree_lines.append(f"{next_prefix}[Error reading directory: {e}]")
+        
+        return tree_lines
+    
+    try:
+        # Generate tree-like representation
+        result = _generate_tree(path)
+        return '\n'.join(result) if result else path.name
+    
+    except OSError as e:
+        raise FileSystemError(f"Failed to generate directory tree for {path}: {e}")

basic_open_agent_tools/file_system/validation.py

@@ -0,0 +1,40 @@
+"""Path validation utilities for file system operations."""
+
+from pathlib import Path
+from ..exceptions import FileSystemError
+
+
+def validate_path(path: str, operation: str) -> Path:
+    """Validate and convert path string to Path object.
+    
+    Args:
+        path: Path string to validate
+        operation: Operation name for error messages
+        
+    Returns:
+        Validated Path object
+        
+    Raises:
+        FileSystemError: If path is invalid
+    """
+    if not path or not isinstance(path, str):
+        raise FileSystemError(f"Invalid path for {operation}: {path}")
+    
+    try:
+        return Path(path).resolve()
+    except (OSError, ValueError) as e:
+        raise FileSystemError(f"Invalid path for {operation}: {path} - {e}")
+
+
+def validate_file_content(content: str, operation: str) -> None:
+    """Validate file content for write operations.
+    
+    Args:
+        content: Content to validate
+        operation: Operation name for error messages
+        
+    Raises:
+        FileSystemError: If content is not a string
+    """
+    if not isinstance(content, str):
+        raise FileSystemError(f"Content must be a string for {operation}")

basic_open_agent_tools/network/TODO.md

@@ -0,0 +1,55 @@
+# Network Tools TODO
+
+## Overview
+Local network utilities and validation tools (no HTTP/API operations).
+
+## Planned Modules
+
+### High Priority
+- [ ] **Validation** (`validation.py`)
+  - URL format validation
+  - IP address validation (IPv4/IPv6)
+  - Port number validation
+  - Domain name validation
+  - Email format validation
+  - Network address validation
+
+- [ ] **Local Utilities** (`local.py`)
+  - Local network interface enumeration
+  - Available port checking
+  - Local IP address discovery
+  - Network connectivity testing (ping-like)
+  - Local hostname resolution
+  - MAC address utilities
+
+### Medium Priority
+- [ ] **Discovery** (`discovery.py`)
+  - Local service discovery
+  - Network scanning (local subnet only)
+  - Port scanning (local only)
+  - Device discovery on local network
+  - Network topology detection
+
+- [ ] **Address Utilities** (`addresses.py`)
+  - IP address manipulation
+  - Subnet calculations
+  - CIDR notation handling
+  - Network range operations
+  - IP address sorting and comparison
+
+### Low Priority
+- [ ] **Protocol Utilities** (`protocols.py`)
+  - Basic protocol detection
+  - Port-to-service mapping
+  - Network protocol validation
+  - Common port definitions
+
+## Design Considerations
+- No external HTTP/API calls (follows project principle)
+- Focus on local network operations only
+- Cross-platform network interface handling
+- Security considerations (no unauthorized scanning)
+- IPv6 compatibility
+- Proper error handling for network operations
+- Timeout handling for network checks
+- Permission awareness for network operations

basic_open_agent_tools/network/__init__.py

@@ -0,0 +1,6 @@
+"""Network tools for AI agents.
+
+This module is not yet implemented. See TODO.md for planned functionality.
+"""
+
+__all__ = []  # No functions available yet

basic_open_agent_tools/system/TODO.md

@@ -0,0 +1,62 @@
+# System Tools TODO
+
+## Overview
+System-level operations and information gathering tools for AI agents.
+
+## Planned Modules
+
+### High Priority
+- [ ] **Process Management** (`process.py`)
+  - Command execution with timeout
+  - Process spawning and monitoring
+  - Subprocess communication
+  - Process tree operations
+  - Safe command execution
+  - Return code handling
+
+- [ ] **Environment Management** (`environment.py`)
+  - Environment variable access
+  - PATH manipulation
+  - Working directory management
+  - User/system information
+  - Platform detection
+  - Shell detection
+
+### Medium Priority
+- [ ] **Resource Monitoring** (`resources.py`)
+  - CPU usage monitoring
+  - Memory usage information
+  - Disk space checking
+  - System load information
+  - Process resource usage
+  - Basic performance metrics
+
+- [ ] **System Information** (`info.py`)
+  - Operating system details
+  - Hardware information (basic)
+  - Network interface enumeration
+  - Timezone and locale information
+  - System uptime and boot time
+  - Available system tools detection
+
+### Low Priority
+- [ ] **Service Management** (`services.py`)
+  - System service status checking
+  - Basic service interaction
+  - Daemon/service utilities
+  - Process management helpers
+
+- [ ] **Logging Integration** (`logging.py`)
+  - System log access (where available)
+  - Log file monitoring
+  - Structured logging helpers
+  - Log rotation utilities
+
+## Design Considerations
+- Cross-platform compatibility (Windows, macOS, Linux)
+- Secure command execution (avoid shell injection)
+- Proper error handling for system operations
+- Resource cleanup (processes, file handles)
+- Permission and security awareness
+- Timeout handling for long-running operations
+- Non-blocking operations where possible

basic_open_agent_tools/system/__init__.py

@@ -0,0 +1,6 @@
+"""System tools for AI agents.
+
+This module is not yet implemented. See TODO.md for planned functionality.
+"""
+
+__all__ = []  # No functions available yet

basic_open_agent_tools/text/TODO.md

@@ -0,0 +1,66 @@
+# Text Processing Tools TODO
+
+## Overview
+Text manipulation, processing, and format conversion tools for AI agents.
+
+## Planned Modules
+
+### High Priority
+- [ ] **Text Processing** (`processing.py`)
+  - String cleaning and normalization
+  - Whitespace handling (strip, normalize, dedent)
+  - Case conversion utilities
+  - Text splitting and joining
+  - Line ending normalization
+  - Unicode handling and normalization
+
+- [ ] **Search Operations** (`search.py`)
+  - Pattern matching and regex utilities
+  - Text search and replacement
+  - Fuzzy string matching
+  - Text extraction from patterns
+  - Multi-line text processing
+
+- [ ] **Format Handling** (`formats.py`)
+  - JSON parsing and formatting
+  - CSV reading and writing
+  - YAML processing (if dependency allowed)
+  - Basic markdown processing
+  - INI/config file parsing
+
+### Medium Priority
+- [ ] **Encoding/Decoding** (`encoding.py`)
+  - Character encoding detection
+  - Encoding conversion (UTF-8, ASCII, etc.)
+  - URL encoding/decoding
+  - HTML entity encoding/decoding
+  - Base64 text operations
+
+- [ ] **Text Analysis** (`analysis.py`)
+  - Character and word counting
+  - Basic text statistics
+  - Language detection (basic)
+  - Text similarity comparison
+  - Keyword extraction
+
+### Low Priority
+- [ ] **Template Processing** (`templates.py`)
+  - Simple string templating
+  - Variable substitution
+  - Basic template engine
+  - Configuration templating
+
+- [ ] **Validation** (`validation.py`)
+  - Text format validation
+  - Input sanitization
+  - Content filtering
+  - Schema-based text validation
+
+## Design Considerations
+- Keep dependencies minimal (prefer standard library)
+- Handle different encodings gracefully
+- Provide both simple and advanced APIs
+- Consistent error handling
+- Memory-efficient for large texts
+- Cross-platform line ending handling
+- Security considerations for text processing

basic_open_agent_tools/text/__init__.py

@@ -0,0 +1,6 @@
+"""Text processing tools for AI agents.
+
+This module is not yet implemented. See TODO.md for planned functionality.
+"""
+
+__all__ = []  # No functions available yet

basic_open_agent_tools/types.py

@@ -0,0 +1,9 @@
+"""Common type definitions for basic-open-agent-tools."""
+
+from typing import Union
+from pathlib import Path
+
+# Common type aliases currently in use
+PathLike = Union[str, Path]
+
+# Additional types will be added as modules are implemented

basic_open_agent_tools/utilities/TODO.md

@@ -0,0 +1,79 @@
+# Utilities TODO
+
+## Overview
+Common utilities and helper functions that don't fit into other categories.
+
+## Planned Modules
+
+### High Priority
+- [ ] **Logging** (`logging.py`)
+  - Structured logging setup
+  - Log formatter utilities
+  - Log level management
+  - File and console logging
+  - Log rotation helpers
+  - Context-aware logging
+
+- [ ] **Configuration** (`configuration.py`)
+  - Configuration file management
+  - Environment-based configuration
+  - Configuration validation
+  - Default value handling
+  - Configuration merging
+  - INI, JSON, YAML config support
+
+- [ ] **Caching** (`caching.py`)
+  - Simple in-memory caching
+  - File-based caching
+  - Cache expiration policies
+  - LRU cache implementations
+  - Cache statistics
+  - Thread-safe caching
+
+### Medium Priority
+- [ ] **Timing** (`timing.py`)
+  - Execution timing utilities
+  - Timeout decorators
+  - Rate limiting helpers
+  - Retry mechanisms with backoff
+  - Performance profiling helpers
+  - Scheduling utilities
+
+- [ ] **Decorators** (`decorators.py`)
+  - Common function decorators
+  - Retry decorators
+  - Timeout decorators
+  - Memoization decorators
+  - Logging decorators
+  - Validation decorators
+
+- [ ] **Error Handling** (`errors.py`)
+  - Custom exception classes
+  - Error reporting utilities
+  - Exception chaining helpers
+  - Error context management
+  - Graceful error handling patterns
+
+### Low Priority
+- [ ] **Helpers** (`helpers.py`)
+  - Common utility functions
+  - Data conversion helpers
+  - Type checking utilities
+  - Default value helpers
+  - Function composition utilities
+
+- [ ] **Testing** (`testing.py`)
+  - Test utilities and helpers
+  - Mock data generation
+  - Test fixture management
+  - Assertion helpers
+  - Test environment setup
+
+## Design Considerations
+- Keep modules focused and cohesive
+- Provide both simple and advanced APIs
+- Thread-safety where applicable
+- Memory efficiency
+- Clear documentation and examples
+- Minimal external dependencies
+- Cross-platform compatibility

basic_open_agent_tools/utilities/__init__.py

@@ -0,0 +1,6 @@
+"""Utility tools for AI agents.
+
+This module is not yet implemented. See TODO.md for planned functionality.
+"""
+
+__all__ = []  # No functions available yet

basic_open_agent_tools-0.1.0.dist-info/METADATA

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: basic-open-agent-tools
+Version: 0.1.0
+Summary: An open foundational toolkit providing essential components for building AI agents with minimal dependencies for local (non-HTTP/API) actions.
+Project-URL: Homepage, https://github.com/open-agent-tools/basic-open-agent-tools
+Project-URL: Documentation, https://github.com/open-agent-tools/basic-open-agent-tools#readme
+Project-URL: Repository, https://github.com/open-agent-tools/basic-open-agent-tools
+Project-URL: Issues, https://github.com/open-agent-tools/basic-open-agent-tools/issues
+Author-email: Open Agent Tools <info@openagenttools.org>
+License: MIT License
+        
+        Copyright (c) 2025 Open Agent Tools
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,ai,automation,local-tools,toolkit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# basic-open-agent-tools
+
+An open foundational toolkit providing essential components for building AI agents with minimal dependencies for local (non-HTTP/API) actions. Designed to offer core utilities and interfaces that developers can easily integrate into their own agents to avoid excess boilerplate, while being simpler than solutions requiring MCP or A2A.
+
+## Installation
+
+```bash
+pip install basic-open-agent-tools
+```
+
+Or with UV:
+```bash
+uv add basic-open-agent-tools
+```
+
+## Usage
+
+```python
+from basic_open_agent_tools import file_system
+
+# File operations
+content = file_system.read_file_to_string("file.txt")
+file_system.write_file_from_string("output.txt", "Hello!")
+
+# Directory operations  
+files = file_system.list_directory_contents("/path/to/dir")
+file_system.create_directory("new_dir")
+```
+
+
+
+
+# Best Practices for Contributors and Reviewers
+
+## Regularly Sync Your Fork/Branch:
+
+Before starting new work or submitting a PR, git pull upstream main to get the latest changes into your local main branch, then rebase your feature branch on top of it.
+
+## Small, Focused Pull Requests:
+
+Break down large features into smaller, atomic PRs.
+
+## Clear Titles and Descriptions:
+
+Use a consistent format (e.g., "Feat: Add user profile page," "Fix: Resolve login bug"). Include context, what changed, why, and how to test. Link to related issues (e.g., "Closes #123").
+
+## Use Draft Pull Requests:
+
+Contributors can open PRs as "Draft" and mark them "Ready for review" when complete. Draft PRs won't trigger required status checks or reviews.
+
+## Descriptive Commit Messages:
+
+Add well-written commit messages (subject line + body for details).
+
+## Self-Review First:
+
+Contributors should review their own PRs thoroughly before requesting reviews.
+
+## Responsive to Feedback:
+
+Contributors should address comments and questions from reviewers promptly. If changes are requested, push new commits to the same branch; the PR will automatically update.
+
+
+

basic_open_agent_tools-0.1.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+basic_open_agent_tools/__init__.py,sha256=_SYS6OtAQSbRN_Zb4eis6d4yq_fxVVCyEPBRJR2zn9s,800
+basic_open_agent_tools/exceptions.py,sha256=FYgYp8GCcxfY_BGQgp1W5EnRCZSqBBpANbc1Zo4fWfY,269
+basic_open_agent_tools/types.py,sha256=_p4m9KtSsNkCgscK2P2zrMNv0p-cWKdj1URGRSFDu-M,237
+basic_open_agent_tools/crypto/TODO.md,sha256=Hur8_7AKP4OJIYn06Je5iDIbjn4hV6YPdBYQ-pTmj5A,1824
+basic_open_agent_tools/crypto/__init__.py,sha256=ycEvqObFD1GOrR7ttr3Xay-Rwc8f-e2F7SMmLUXLlLE,162
+basic_open_agent_tools/data/TODO.md,sha256=SETVwuxUkP9AoDm01yYQJ9aJHVJC-EVbBBWrIo4tG5w,1977
+basic_open_agent_tools/data/__init__.py,sha256=8tkNs8AIEJLSQjDYE14ry8EV7Zi0E6yMNeg4r4STnGo,153
+basic_open_agent_tools/file_system/TODO.md,sha256=_geHQx_hzmCv-hyXygOY4k7UCq7vO1vs94MfWA9IofY,2002
+basic_open_agent_tools/file_system/__init__.py,sha256=GKslHUOcWRcBSVgYDSEJkcjkdl6Bya8FdYzGL8B5T2s,1655
+basic_open_agent_tools/file_system/info.py,sha256=MJpjyoBcFxBI3wq_rsrbPuAqAlpnezuNd0Cje4Y-ye8,3110
+basic_open_agent_tools/file_system/operations.py,sha256=nRgff4FyZQ089nXk0J8UA66JCA_gTjsySSGb7sIA2Og,6513
+basic_open_agent_tools/file_system/tree.py,sha256=El1L8e67rm7pqrYqFBXXxtMo3Wl1tfInnH2NZ6w8yDg,5130
+basic_open_agent_tools/file_system/validation.py,sha256=8DLOAqsJM_Oi-HCMEfuCCTAqRwtjnpu5mJKXtRjTkx4,1168
+basic_open_agent_tools/network/TODO.md,sha256=1XgSXg9iBo0vGlLWtiS_TpTGq_B_pyuM3VI90LvymZw,1572
+basic_open_agent_tools/network/__init__.py,sha256=oz5dLofvEURWmjBSv5F_oBcW0S6Fif3A41Im_WgSMcQ,156
+basic_open_agent_tools/system/TODO.md,sha256=gv2b0loew0-wd7ZBorPteXGp-MgWBYu9zNj2P1_aBfc,1754
+basic_open_agent_tools/system/__init__.py,sha256=AzFfXB_xU3ky1SUUW04drvvu4Fpy5ouduu1RbaNkrCI,155
+basic_open_agent_tools/text/TODO.md,sha256=t7JMeOgMtb6GIyDJJH_HmgnhfPsbymxLmF17gZu_JQ8,1869
+basic_open_agent_tools/text/__init__.py,sha256=oaClrpc_F_lSeuhr7MOyNAGjgbQJjMK9pWrQ49RhCCU,164
+basic_open_agent_tools/utilities/TODO.md,sha256=OIAVtnrawLU5qZpyW3kTvHiHfPpQkRrNhRtz1r3577c,1992
+basic_open_agent_tools/utilities/__init__.py,sha256=fIq1GU6ryoQE8rLpgGpvhkFoM62HLWIz0N4M9HWotSc,156
+basic_open_agent_tools-0.1.0.dist-info/METADATA,sha256=kaOt0aGsMV-5UZ549DO1vClck9NfrgoLAb3spsV7hY8,4964
+basic_open_agent_tools-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+basic_open_agent_tools-0.1.0.dist-info/licenses/LICENSE,sha256=4yVsLRHKwmGobVox6N7LAsrmXo52Sytn6XFnHgxXGnE,1073
+basic_open_agent_tools-0.1.0.dist-info/RECORD,,

basic_open_agent_tools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

basic_open_agent_tools-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Open Agent Tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.