torivers-sdk 0.2.0b2

SDK for building third-party automations for the ToRivers marketplace

ToRivers SDK

Build and publish automations for the ToRivers marketplace.

Installation

pip install torivers-sdk

Quick Start

Create a new automation:

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:

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

# 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

Versioning & Releases

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

pip install -e ".[dev]"

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

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:

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 for details.