# ToRivers SDK

Build and publish automations for the ToRivers marketplace.

## Installation

```bash
pip install torivers-sdk
```

## Quick Start

Create a new automation:

```python
from torivers_sdk import Automation, AutomationMetadata, BaseState
from langgraph.graph import StateGraph
from typing import Annotated, Any


class MyState(BaseState):
    """State for my automation."""
    result: Annotated[str, lambda l, r: r]


class MyAutomation(Automation[MyState]):
    """A simple automation example."""

    def metadata(self) -> AutomationMetadata:
        return AutomationMetadata(
            name="my-automation",
            title="My Automation",
            version="1.0.0",
            description="Does something useful",
            category="general",
        )

    def get_state_class(self) -> type[MyState]:
        return MyState

    def build_graph(self) -> StateGraph:
        graph = StateGraph(MyState)
        graph.add_node("process", self.process)
        graph.set_entry_point("process")
        graph.set_finish_point("process")
        return graph

    def process(self, state: MyState) -> dict[str, Any]:
        context = state["context"]
        context.log_progress("Processing", "Starting work...")

        # Your automation logic here
        result = f"Processed: {state['input_data']}"

        context.log_success("Done", "Work completed!")
        return {
            "output_data": {
                "_version": 1,
                "_blocks": [
                    {
                        "type": "text",
                        "label": "Result",
                        "content": result,
                        "format": "plain",
                    }
                ],
            }
        }
```

## Testing Locally

Use the local sandbox to test your automation:

```python
import asyncio
from torivers_sdk.testing import LocalSandbox, MockCredentialProxy

async def test_automation():
    sandbox = LocalSandbox()

    # Set up mock credentials if needed
    credentials = MockCredentialProxy(["gmail", "sheets"])
    sandbox.set_credentials(credentials)

    # Run the automation
    automation = MyAutomation()
    result = await sandbox.run(automation, {"query": "test"})

    assert result.success
    print(f"Output: {result.output_data}")

asyncio.run(test_automation())
```

## CLI Commands

```bash
# Initialize a new automation project
torivers init my-automation

# Run locally
torivers run --input input.json

# Run tests
torivers test

# Validate before submission
torivers validate

# Submit for review
torivers submit

# Authenticate and track review
torivers login
torivers status
```

## Documentation

For full documentation, visit [docs.torivers.com/sdk](https://docs.torivers.com/sdk)

## Versioning & Releases

This package uses `bump-my-version` for version management. Install dev dependencies first:

```bash
pip install -e ".[dev]"
```

Bump the version (creates a commit + `sdk-v*` tag automatically):

```bash
bump-my-version bump patch                   # 0.1.0 → 0.1.1
bump-my-version bump minor                   # 0.1.0 → 0.2.0
bump-my-version bump --new-version 0.2.0b1   # Start a beta cycle
bump-my-version bump pre_n                   # Next beta (b1 → b2)
bump-my-version bump pre_l                   # Beta → RC → Stable
```

Then push to trigger the PyPI publish workflow:

```bash
git push && git push --tags
```

Pre-releases (`b`/`rc` tags) are published to PyPI but not installed by default — users must `pip install --pre torivers-sdk`.

## Requirements

- Python 3.11+
- Dependencies: langgraph, pydantic, httpx, click, rich, docker, pyyaml

## License

Proprietary - see [LICENSE](LICENSE) for details.
