feat: Simplify library import and usage

[codegen-sh]

📦 Developer Experience Enhancement

This PR implements the "Simplify Library Import and Usage" task to make grain-chain significantly easier to use for new developers and common use cases.

🚀 Key Improvements

Import Simplification

• ✅ Added convenience imports to main grainchain/__init__.py
• ✅ Created Providers class with constants (LOCAL, E2B, DAYTONA, MORPH, MODAL)
• ✅ Added factory functions: create_local_sandbox(), create_e2b_sandbox(), create_sandbox()
• ✅ Maintained full backward compatibility

API Design Enhancements

• ✅ Added QuickSandbox class for synchronous operations (no async/await needed)
• ✅ Created convenience functions: quick_execute(), quick_python(), quick_script()
• ✅ Implemented ConfigPresets with predefined configurations for development, testing, and data science
• ✅ Added smart defaults and environment variable handling

Usage Examples

• ✅ Created comprehensive examples in examples/ directory:
  • hello_world.py - Simple getting started example
  • simplified_usage.py - Demonstrates new API patterns
  • integration_patterns.py - Shows integration with other tools
  • sync_usage_demo.py - Synchronous API demonstration

Testing & Quality

• ✅ Added comprehensive test coverage for all new functionality
• ✅ All existing tests continue to pass
• ✅ Code quality checks pass (ruff, formatting)
• ✅ Thread-safe async/sync bridging implementation

💡 Before vs After

Before (Complex)

from grainchain.core.sandbox import Sandbox
from grainchain.core.interfaces import SandboxConfig
import asyncio

async def main():
    config = SandboxConfig(timeout=60, working_directory="~")
    async with Sandbox(provider="local", config=config) as sandbox:
        result = await sandbox.execute("echo 'Hello'")
        print(result.stdout)

asyncio.run(main())

After (Simple)

from grainchain import create_local_sandbox
# OR even simpler:
from grainchain.convenience import quick_execute

# Async version (simplified)
async with create_local_sandbox() as sandbox:
    result = await sandbox.execute("echo 'Hello'")
    print(result.stdout)

# Sync version (no async needed!)
result = quick_execute("echo 'Hello'")
print(result.stdout)

🔧 Technical Implementation

Thread-Safe Synchronous API

• Implemented QuickSandbox with intelligent async/sync bridging
• Handles event loop conflicts when running in async contexts
• Uses separate threads when necessary to avoid blocking
• Proper resource cleanup and error handling

Smart Configuration

• Factory functions with sensible defaults
• Configuration presets for common use cases
• Environment variable merging and handling
• Provider-specific optimizations

Backward Compatibility

• All existing APIs continue to work unchanged
• Optional imports with graceful fallbacks
• No breaking changes to existing functionality

📊 Impact

This significantly improves developer adoption by:

• Reducing friction for new users (3 lines of code to get started)
• Making async optional for simple use cases
• Providing clear patterns for common scenarios
• Maintaining power for advanced users
• Improving integration with existing Python codebases

🧪 Testing

All examples work out of the box:

python examples/hello_world.py
python examples/sync_usage_demo.py
python examples/simplified_usage.py

Test coverage includes:

• Provider constants and factory functions
• Synchronous API functionality
• Configuration presets
• Error handling and edge cases
• Thread safety and async/sync bridging

✅ Success Criteria Met

• New users can import and use grain-chain in 3 lines of code
• Examples work out of the box
• API feels intuitive and pythonic
• Clear patterns for common use cases
• Good integration with popular tools
• Backward compatibility maintained
• Comprehensive test coverage

---

💻 View my work • About Codegen