Metadata-Version: 2.5
Name: fluidgrids-sdk
Version: 2026.1021.1
Summary: Official Python SDK for FluidGrids - Workflow Automation Platform (thin shell over burdenoff-sdk-libs)
Project-URL: Homepage, https://github.com/algoshred/fluidgrids-sdk-python
Project-URL: Documentation, https://docs.algoshred.com/sdk/python
Project-URL: Repository, https://github.com/algoshred/fluidgrids-sdk-python
Project-URL: Issues, https://github.com/algoshred/fluidgrids-sdk-python/issues
Project-URL: Changelog, https://github.com/algoshred/fluidgrids-sdk-python/blob/main/CHANGELOG.md
Author-email: FluidGrids <info@fluidgrids.ai>, "Vignesh T.V" <vignesh@algoshred.com>
Maintainer-email: FluidGrids <info@fluidgrids.ai>
License: Copyright (c) 2025 Algoshred Technologies Private Limited.
        
        All rights reserved.
        
        This software is proprietary and confidential. Unauthorized copying, modification, distribution, or use of this software, via any medium, is strictly prohibited without the express written permission of the copyright holders.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
        For licensing inquiries, please contact: legal@algoshred.com
License-File: LICENSE
Keywords: api-client,automation,fluidgrids,graphql,python,sdk,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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: burdenoff-sdk-libs>=2026.1021.1
Requires-Dist: httpx>=0.24.0
Requires-Dist: typing-extensions>=4.0.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=0.10.0; extra == 'dev'
Requires-Dist: flake8>=6.0.0; extra == 'dev'
Requires-Dist: graphql-core>=3.2.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: twine>=4.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-autodoc-typehints>=1.19.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == 'docs'
Requires-Dist: sphinx>=6.0.0; extra == 'docs'
Provides-Extra: test
Requires-Dist: graphql-core>=3.2.0; extra == 'test'
Requires-Dist: httpx[testing]>=0.24.0; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

# FluidGrids Python SDK

Official Python SDK for [FluidGrids](https://fluidgrids.ai), the workflow
automation platform.

It is a **thin shell over [`burdenoff-sdk-libs`](https://pypi.org/project/burdenoff-sdk-libs/)**,
like `vibecontrols-sdk`: FluidGrids operations live in the shared `fluidgrids`
module (`sdk.fluidgrids`), and the platform modules are mounted alongside
(`sdk.auth`, `sdk.workspaces`, `sdk.tags`, `sdk.files`, `sdk.billing`,
`sdk.notifications`, `sdk.support`, `sdk.store`, `sdk.integrations`, …).

## Installation

`fluidgrids-sdk` is not on PyPI yet. Install from source:

```bash
pip install -e .        # pulls burdenoff-sdk-libs from PyPI
```

Requires Python 3.10+.

## Quick start

```python
import asyncio
from fluidgrids_sdk import FluidGridsSDK

async def main() -> None:
    async with FluidGridsSDK(access_token=token, refresh_token=refresh) as sdk:
        # Workspace calls need a workspace token as well as the platform token.
        await sdk.auth.issue_workspace_token(workspace_id, organization_id)

        page = await sdk.fluidgrids.workflows.list({"status": "ACTIVE", "limit": 20})
        run = await sdk.fluidgrids.workflows.trigger(
            {"workflow_key": "invoice-sync", "version": "1.0.0", "trigger_node_id": "start",
             "trigger_data": {"amount": 42}}
        )
        done = await sdk.fluidgrids.runs.wait_for_completion(run.run_id, timeout=600)
        logs = await sdk.fluidgrids.runs.logs(run.run_id, min_level="WARN")

asyncio.run(main())
```

Get tokens with any `sdk.auth` flow: device code, PKCE, or client credentials
for automation.

## The FluidGrids module

| Namespace | Operations |
|---|---|
| `fluidgrids.workflows` | `list`, `get(id)` / `get(workflow_key=, version=)`, `versions`, `create`, `update`, `delete`, `trigger`, `publish`, `activate`, `deactivate`, `archive`, `duplicate`, `import_template` |
| `fluidgrids.runs` | `list`, `get`, `logs`, `cancel`, `pause`, `resume`, `retry_node(run_id, node_id)`, `wait_for_completion` |
| `fluidgrids.nodes` | `list`, `get(node_type, node_version)` |
| `fluidgrids.credentials` | `list`, `get`, `list_types`, `create`, `authenticate_with_api_key`, `authenticate_with_basic_auth`, `update`, `delete`, `test` |
| `fluidgrids.webhooks` | `list`, `get`, `create`, `update`, `delete`, `toggle` |
| `fluidgrids.scheduled_jobs` | `list`, `get`, `create`, `update`, `delete`, `set_enabled` |
| `fluidgrids.dashboard` | `summary`, `usage({"start_date", "end_date"})` |
| `fluidgrids.search` | `search`, `by_entity_type` |
| `fluidgrids.admin` | `system_info` |

Responses are snake_case dataclasses. Inputs are snake_case dicts; only their
top-level keys are converted to GraphQL names, so JSON values such as
`definition_json` or `trigger_data` are sent exactly as given.

A credential is an integration connection, created in two steps: `create` (no
secret material), then `authenticate_with_api_key` / `authenticate_with_basic_auth`.

## Configuration

| Argument / env | Default |
|---|---|
| `workspace_endpoint` / `FLUIDGRIDS_WORKSPACE_ENDPOINT` | `https://graphqlworkspaces.burdenoff.com/workspaces/graphql` |
| `global_endpoint` / `FLUIDGRIDS_GLOBAL_ENDPOINT` | `https://graphql.burdenoff.com/global/graphql` |
| `product_origin` / `FLUIDGRIDS_ORIGIN` | `https://app.fluidgrids.ai` (prod), `https://alphaapp.fluidgrids.ai` (alpha) |

The workflow service is product-scoped: the gateway works out the product from
the request `Origin`, which httpx does not send by itself. The SDK sets it for
the production and alpha gateways; pass `product_origin` for a custom or local
gateway.

## Development

```bash
python -m venv .venv && .venv/bin/pip install -e ".[dev,test]"
make sanity
```

`tests/test_graphql_documents.py` validates every FluidGrids document against the
vendored `schema/wspace.graphql` (see schema/README.md to refresh it). Change
FluidGrids behaviour in sdk-libs-python (`modules/fluidgrids/`) and its Node twin;
this repo only picks modules and product defaults.

## License

Proprietary — Copyright (c) Algoshred Technologies Private Limited
