Implement JSON and CSV data processing tools (Phase 1)

[jwesleye]

Summary

This PR implements Phase 1 of the data processing module, adding comprehensive JSON and CSV processing capabilities to the basic-open-agent-tools project.

🚀 New Features

Infrastructure Added:

• ✅ Data-specific exception classes (DataError, ValidationError, SerializationError)
• ✅ Type definitions for data operations (DataDict, NestedData, ValidationResult)
• ✅ Helper functions for selective tool loading by category

JSON Processing Tools (json_tools.py - 5 functions):

• safe_json_serialize() - JSON serialization with comprehensive error handling
• safe_json_deserialize() - Safe JSON parsing with validation
• validate_json_string() - JSON validation without parsing overhead
• compress_json_data() / decompress_json_data() - Gzip compression for efficient storage

CSV Processing Tools (csv_tools.py - 7 functions):

• read_csv_file() / write_csv_file() - File I/O with flexible delimiter and header options
• csv_to_dict_list() / dict_list_to_csv() - String-based CSV conversion
• detect_csv_delimiter() - Automatic delimiter detection
• validate_csv_structure() - Structure and column validation
• clean_csv_data() - Configurable data cleaning with rules

📊 Quality Metrics

• 71 comprehensive tests covering all edge cases and error conditions
• 91% test coverage for CSV tools, 100% for JSON tools
• 12 new agent functions now available
• ✅ Full ruff/mypy compliance maintained
• 🔒 Zero external dependencies added (pure Python stdlib)

🤖 Agent Integration

import basic_open_agent_tools as boat

# Load all data tools (12 functions)
data_tools = boat.load_all_data_tools()

# Or load by specific category
json_tools = boat.load_data_json_tools()    # 5 functions
csv_tools = boat.load_data_csv_tools()      # 7 functions

# Merge with existing tools for comprehensive agent toolkit
all_tools = boat.merge_tool_lists(
    boat.load_all_filesystem_tools(),  # 18 functions
    boat.load_all_text_tools(),        # 10 functions  
    boat.load_all_data_tools()         # 12 functions
)
# Total: 40 functions available for agent workflows

🎯 Architecture Highlights

• Agent-first design: Each function works as a standalone tool
• Type safety: Full type annotations with mypy compliance
• Error handling: Consistent exception patterns with descriptive messages
• Security-conscious: Input validation and safe parsing
• Memory efficient: Streaming support for large files planned
• Extensible: Clean foundation for Phase 2 (data structures, validation)

📋 Test Coverage

All functions include comprehensive testing:

• ✅ Positive test cases for normal operation
• ✅ Edge cases (empty data, boundary conditions)
• ✅ Error condition testing with proper exception handling
• ✅ Type validation for all parameters
• ✅ Round-trip validation for serialization
• ✅ Unicode and special character support

🔄 Next Steps (Phase 2)

This implementation provides the foundation for:

• Data structure manipulation tools
• Advanced validation capabilities
• Configuration file processing (YAML/TOML/INI)
• Data transformation utilities

✅ Checklist

• All ruff linting checks pass
• All mypy type checks pass
• 71/71 tests passing
• Documentation complete with examples
• Helper functions integrated
• Main package exports updated
• Zero breaking changes to existing functionality

Test plan

• Run full test suite: python3 -m pytest
• Verify tool loading: Test all helper functions work correctly
• Check integration: Ensure data tools merge properly with existing tools
• Validate imports: Confirm all functions are properly exported
• Test coverage: Verify 70%+ coverage maintained across project

🤖 Generated with Claude Code