loco-sdk 0.1.0__tar.gz

loco_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to the Loco SDK will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-14
+
+### Added
+- Initial release
+- NodePlugin base class for workflow nodes
+- PluginBase abstract class
+- ExtensionPlugin and TriggerPlugin base classes
+- AuthContext helper for OAuth2, API key, and basic auth
+- Exception hierarchy (PluginError, AuthenticationError, etc.)
+- Comprehensive test suite with pytest
+- Development tools: black, ruff, mypy
+- uv support for dependency management
+- DEVELOPMENT.md guide
+
+### Changed
+- N/A (initial release)
+
+### Deprecated
+- N/A
+
+### Removed
+- N/A
+
+### Fixed
+- N/A
+
+### Security
+- N/A
+
+## [Unreleased]
+
+### Planned
+- Pydantic schemas for manifest validation
+- Manifest loader utilities
+- OAuth provider configurations
+- Backwards invocation client (call Loco services from plugins)
+- File operation helpers
+- HTTP client with retry logic
+- More authentication methods

loco_sdk-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,303 @@
+# Development Guide
+
+## Setup Development Environment
+
+### Prerequisites
+- Python 3.11+
+- uv (recommended) or pip
+
+### Install with uv (Recommended)
+
+```bash
+# Install uv if not already installed
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Navigate to SDK directory
+cd packages/loco-plugin-sdk
+
+# Create virtual environment and install dependencies
+uv venv
+source .venv/bin/activate  # Linux/macOS
+# or
+.venv\Scripts\activate  # Windows
+
+# Install package with dev dependencies
+uv pip install -e ".[dev]"
+```
+
+### Install with pip
+
+```bash
+cd packages/loco-plugin-sdk
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # Linux/macOS
+.venv\Scripts\activate  # Windows
+
+# Install package with dev dependencies
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+### Run all tests
+
+```bash
+# With pytest
+pytest
+
+# With coverage
+pytest --cov=loco_plugin_sdk --cov-report=html
+
+# Verbose output
+pytest -v
+```
+
+### Run specific tests
+
+```bash
+# Test specific file
+pytest tests/test_auth_context.py
+
+# Test specific function
+pytest tests/test_auth_context.py::test_auth_context_oauth2_get_header
+
+# Test with keyword
+pytest -k "oauth"
+```
+
+### Watch mode (requires pytest-watch)
+
+```bash
+pip install pytest-watch
+ptw
+```
+
+## Code Quality
+
+### Format code
+
+```bash
+# Format with black
+black src tests
+
+# Check formatting
+black --check src tests
+```
+
+### Lint code
+
+```bash
+# Run ruff
+ruff check src tests
+
+# Auto-fix issues
+ruff check --fix src tests
+```
+
+### Type checking
+
+```bash
+# Run mypy
+mypy src
+```
+
+### All checks
+
+```bash
+# Format, lint, and test
+black src tests && ruff check src tests && pytest
+```
+
+## Project Structure
+
+```
+packages/loco-plugin-sdk/
+├── src/
+│   └── loco_plugin_sdk/
+│       ├── __init__.py       # Public API
+│       ├── version.py        # Version info
+│       ├── core/             # Base classes
+│       │   ├── base.py       # NodePlugin
+│       │   ├── exceptions.py # Exception hierarchy
+│       │   └── __init__.py
+│       ├── auth/             # Auth helpers
+│       │   ├── context.py    # AuthContext
+│       │   └── __init__.py
+│       ├── schemas/          # Future: Pydantic models
+│       └── utils/            # Future: Utilities
+├── tests/
+│   ├── conftest.py           # Pytest fixtures
+│   ├── test_auth_context.py # AuthContext tests
+│   ├── test_node_plugin.py  # NodePlugin tests
+│   └── test_exceptions.py   # Exception tests
+├── pyproject.toml            # Package config
+├── README.md                 # User documentation
+└── DEVELOPMENT.md            # This file
+```
+
+## Adding New Features
+
+### 1. Create the feature
+
+```python
+# src/loco_plugin_sdk/myfeature.py
+def my_function():
+    """My new feature."""
+    pass
+```
+
+### 2. Export in __init__.py
+
+```python
+# src/loco_plugin_sdk/__init__.py
+from loco_plugin_sdk.myfeature import my_function
+
+__all__ = [
+    # ... existing
+    "my_function",
+]
+```
+
+### 3. Add tests
+
+```python
+# tests/test_myfeature.py
+def test_my_function():
+    """Test my new feature."""
+    result = my_function()
+    assert result is not None
+```
+
+### 4. Update documentation
+
+Update README.md with usage examples.
+
+## Publishing
+
+### Build package
+
+```bash
+# Install build tools
+pip install build twine
+
+# Build distributions
+python -m build
+
+# Check build
+twine check dist/*
+```
+
+### Publish to PyPI
+
+```bash
+# Test PyPI (recommended first)
+twine upload --repository testpypi dist/*
+
+# Production PyPI
+twine upload dist/*
+```
+
+### Version bumping
+
+```bash
+# Update version in src/loco_plugin_sdk/version.py
+__version__ = "0.2.0"
+
+# Update version in pyproject.toml
+version = "0.2.0"
+
+# Commit and tag
+git commit -am "Bump version to 0.2.0"
+git tag v0.2.0
+git push && git push --tags
+```
+
+## Continuous Integration
+
+### GitHub Actions (example)
+
+```yaml
+name: Tests
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        pip install -e ".[dev]"
+    
+    - name: Run tests
+      run: |
+        pytest --cov=loco_plugin_sdk --cov-report=xml
+    
+    - name: Upload coverage
+      uses: codecov/codecov-action@v3
+```
+
+## Best Practices
+
+### Code Style
+- Follow PEP 8
+- Use type hints
+- Write docstrings for public APIs
+- Keep functions small and focused
+
+### Testing
+- Write tests for new features
+- Maintain >80% code coverage
+- Use descriptive test names
+- Test edge cases and errors
+
+### Documentation
+- Update README for user-facing changes
+- Add inline comments for complex logic
+- Keep CHANGELOG.md updated
+
+### Version Control
+- Use feature branches
+- Write clear commit messages
+- Squash commits before merging
+- Tag releases
+
+## Troubleshooting
+
+### Import errors
+
+```bash
+# Reinstall in editable mode
+pip install -e .
+```
+
+### Test failures
+
+```bash
+# Run with verbose output
+pytest -vv
+
+# Show print statements
+pytest -s
+```
+
+### Coverage not working
+
+```bash
+# Ensure coverage installed
+pip install pytest-cov
+
+# Clear cache
+pytest --cache-clear
+```

loco_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,16 @@
+# Package metadata
+include README.md
+include CHANGELOG.md
+include DEVELOPMENT.md
+include LICENSE
+
+# Source code
+recursive-include src/loco_plugin_sdk *.py
+
+# Tests
+recursive-include tests *.py
+
+# Exclude
+global-exclude __pycache__
+global-exclude *.py[cod]
+global-exclude .DS_Store

loco_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: loco-sdk
+Version: 0.1.0
+Summary: Loco SDK for building plugins and shared utilities
+Author: Loco Team
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+
+# Loco Plugin SDK
+
+Official SDK for building Loco workflow plugins.
+
+## Installation
+
+### For Plugin Development
+
+```bash
+# Using pip
+pip install loco-plugin-sdk
+
+# Using uv (recommended)
+uv pip install loco-plugin-sdk
+```
+
+### For SDK Development
+
+```bash
+# Clone repository
+cd packages/loco-plugin-sdk
+
+# Install with dev dependencies using uv
+uv venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+uv pip install -e ".[dev]"
+
+# Or with pip
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from loco_plugin_sdk import NodePlugin
+
+class MyNode(NodePlugin):
+    """My custom node."""
+    
+    async def execute(self, inputs: dict, context: dict) -> dict:
+        """
+        Execute node logic.
+        
+        Args:
+            inputs: Node input values
+            context: Workflow execution context with auth, sys_vars, etc.
+            
+        Returns:
+            Output values dictionary
+        """
+        # Get authentication if needed
+        auth = context.get("auth")
+        if auth:
+            headers = auth.get_header()
+            # Use headers for API calls
+        
+        # Process inputs
+        result = do_something(inputs)
+        
+        # Return outputs
+        return {"result": result}
+```
+
+## Authentication Helper
+
+The SDK provides `AuthContext` to easily work with credentials:
+
+```python
+from loco_sdk import NodePlugin, AuthContext
+
+class MyNode(NodePlugin):
+    async def execute(self, inputs: dict, context: dict) -> dict:
+        # Wrap auth dict with helper
+        auth = AuthContext(context.get("auth"))
+        
+        # Get Authorization header
+        headers = auth.get_header()
+        # Returns: {"Authorization": "Bearer <token>"}
+        
+        # Check token expiry
+        if auth.is_expired():
+            raise AuthenticationError("Token expired")
+        
+        # Access properties
+        provider = auth.provider  # e.g., "google"
+        scopes = auth.scopes      # OAuth scopes
+        
+        # Use in API calls
+        response = await client.get(url, headers=headers)
+        return {"data": response.json()}
+```
+
+## Features
+
+- **NodePlugin Base Class**: Simple interface for workflow nodes
+- **AuthContext Helper**: Easy OAuth2/API key authentication
+- **Type Safety**: Full Pydantic schema support (coming soon)
+- **Manifest Loading**: Parse plugin.yaml files (coming soon)
+- **Testing**: Comprehensive test suite with pytest
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development guide including:
+- Setting up development environment with uv
+- Running tests with pytest
+- Code formatting and linting
+- Publishing to PyPI
+
+### Quick Commands
+
+```bash
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=loco_plugin_sdk --cov-report=html
+
+# Format code
+black src tests
+
+# Lint code
+ruff check src tests
+
+# Type check
+mypy src
+```
+
+## Documentation
+
+See [docs/](docs/) for detailed guides (coming soon).
+
+## Version
+
+0.1.0

loco_sdk-0.1.0/README.md

@@ -0,0 +1,134 @@
+# Loco Plugin SDK
+
+Official SDK for building Loco workflow plugins.
+
+## Installation
+
+### For Plugin Development
+
+```bash
+# Using pip
+pip install loco-plugin-sdk
+
+# Using uv (recommended)
+uv pip install loco-plugin-sdk
+```
+
+### For SDK Development
+
+```bash
+# Clone repository
+cd packages/loco-plugin-sdk
+
+# Install with dev dependencies using uv
+uv venv
+source .venv/bin/activate  # or .venv\Scripts\activate on Windows
+uv pip install -e ".[dev]"
+
+# Or with pip
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from loco_plugin_sdk import NodePlugin
+
+class MyNode(NodePlugin):
+    """My custom node."""
+    
+    async def execute(self, inputs: dict, context: dict) -> dict:
+        """
+        Execute node logic.
+        
+        Args:
+            inputs: Node input values
+            context: Workflow execution context with auth, sys_vars, etc.
+            
+        Returns:
+            Output values dictionary
+        """
+        # Get authentication if needed
+        auth = context.get("auth")
+        if auth:
+            headers = auth.get_header()
+            # Use headers for API calls
+        
+        # Process inputs
+        result = do_something(inputs)
+        
+        # Return outputs
+        return {"result": result}
+```
+
+## Authentication Helper
+
+The SDK provides `AuthContext` to easily work with credentials:
+
+```python
+from loco_sdk import NodePlugin, AuthContext
+
+class MyNode(NodePlugin):
+    async def execute(self, inputs: dict, context: dict) -> dict:
+        # Wrap auth dict with helper
+        auth = AuthContext(context.get("auth"))
+        
+        # Get Authorization header
+        headers = auth.get_header()
+        # Returns: {"Authorization": "Bearer <token>"}
+        
+        # Check token expiry
+        if auth.is_expired():
+            raise AuthenticationError("Token expired")
+        
+        # Access properties
+        provider = auth.provider  # e.g., "google"
+        scopes = auth.scopes      # OAuth scopes
+        
+        # Use in API calls
+        response = await client.get(url, headers=headers)
+        return {"data": response.json()}
+```
+
+## Features
+
+- **NodePlugin Base Class**: Simple interface for workflow nodes
+- **AuthContext Helper**: Easy OAuth2/API key authentication
+- **Type Safety**: Full Pydantic schema support (coming soon)
+- **Manifest Loading**: Parse plugin.yaml files (coming soon)
+- **Testing**: Comprehensive test suite with pytest
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development guide including:
+- Setting up development environment with uv
+- Running tests with pytest
+- Code formatting and linting
+- Publishing to PyPI
+
+### Quick Commands
+
+```bash
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=loco_plugin_sdk --cov-report=html
+
+# Format code
+black src tests
+
+# Lint code
+ruff check src tests
+
+# Type check
+mypy src
+```
+
+## Documentation
+
+See [docs/](docs/) for detailed guides (coming soon).
+
+## Version
+
+0.1.0

loco_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "loco-sdk"
+version = "0.1.0"
+description = "Loco SDK for building plugins and shared utilities"
+authors = [{name = "Loco Team"}]
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+
+dependencies = [
+    "pydantic>=2.0.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "black>=23.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=68.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.black]
+line-length = 100
+target-version = ['py311']
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["src"]
+omit = ["*/tests/*", "*/test_*.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true

loco_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+