Metadata-Version: 2.4
Name: loco-sdk
Version: 0.2.5
Summary: Loco SDK for building plugins and shared utilities
Author: Loco Team
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
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"
Dynamic: license-file

# Loco SDK

[![CI](https://github.com/YOUR_ORG/loco-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR_ORG/loco-sdk/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/YOUR_ORG/loco-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/YOUR_ORG/loco-sdk)
[![PyPI version](https://badge.fury.io/py/loco-sdk.svg)](https://badge.fury.io/py/loco-sdk)
[![Python versions](https://img.shields.io/pypi/pyversions/loco-sdk.svg)](https://pypi.org/project/loco-sdk/)

Official SDK for building Loco workflow plugins.

## Installation

### For Plugin Development

```bash
# Using pip
pip install loco-sdk

# Using uv (recommended)
uv pip install loco-sdk
```

### For SDK Development

```bash
# Clone repository
cd packages/loco-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_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.

### Quick Setup

```bash
# Install dependencies
make install

# Install pre-commit hooks (optional)
pip install pre-commit
pre-commit install
```

### Quick Commands

Use the Makefile for common tasks:

```bash
# Show all available commands
make help

# Run tests with coverage
make test

# Format code
make format

# Lint code
make lint

# Type check
make type-check

# Run all quality checks
make quality

# Build package
make build

# Clean build artifacts
make clean
```

Or use commands directly:

```bash
# Run tests
pytest --cov=loco_sdk --cov-report=html -v

# Format code
black src tests

# Lint code
ruff check src tests

# Type check
mypy src
```

### CI/CD

This project uses GitHub Actions for CI/CD:
- **CI Pipeline**: Runs tests, linting, type checking on every push/PR
- **Publish Pipeline**: Automatically publishes to PyPI on releases
- **Dependabot**: Keeps dependencies up to date

See [.github/workflows/README.md](.github/workflows/README.md) for details.

## Documentation

See [docs/](docs/) for detailed guides (coming soon).

## Version

0.1.0
