Metadata-Version: 2.4
Name: torivers-sdk
Version: 0.2.0b1
Summary: SDK for building third-party automations for the ToRivers marketplace
Project-URL: Homepage, https://torivers.com
Project-URL: Documentation, https://docs.torivers.com/sdk
Project-URL: Repository, https://github.com/torivers/torivers-sdk
Author-email: ToRivers <dev@torivers.com>
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
Keywords: ai,automation,langgraph,marketplace,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: croniter>=2.0.0
Requires-Dist: docker>=7.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: bump-my-version>=1.2.0; extra == 'dev'
Requires-Dist: flake8>=7.0.0; extra == 'dev'
Requires-Dist: isort>=5.13.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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.
