Metadata-Version: 2.5
Name: fluidgrids-sdk
Version: 2026.1117.2
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.1115.2
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: subscriptions
Requires-Dist: websockets>=13.1; extra == 'subscriptions'
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

```bash
pip install fluidgrids-sdk
pip install "fluidgrids-sdk[subscriptions]"   # also websockets, to follow runs live
```

`fluidgrids-sdk` is published on PyPI and requires Python 3.10+. To work on the
SDK itself, install it from a checkout with `pip install -e ".[dev,test]"` (see
Development below). The full guide is at
[docs.fluidgrids.ai/developers/python-sdk](https://docs.fluidgrids.ai/developers/python-sdk).

## 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`, `iterate`, `get(id)` / `get(workflow_key=, version=)`, `versions`, `summary`, `diff_versions`, `create`, `update`, `delete`, `trigger`, `publish`, `activate`, `deactivate`, `archive`, `duplicate`, `import_template`, `restore_version`, `execute_step`, `export`, `import_`, `create_version`, `validate`, `interface`, `start`, `start_with_update` |
| `fluidgrids.runs` | `list`, `iterate`, `get`, `logs`, `iterate_logs`, `hierarchy`, `node_states`, `node_state`, `cancel`, `pause`, `resume`, `retry_node(run_id, node_id)`, `replay`, `retry`, `run_from_node`, `can_run_from_node`, `wait_for_completion`, `watch`, `watch_node_states`, `stream_logs`, `describe`, `by_workflow_id`, `pending`, `count`, `history`, `history_all`, `signal`, `stack_trace`, `determinism`, `terminate`, `result`, `query`, `update`, `update_result`, `reset`, `batch.start\|get\|list\|cancel` |
| `fluidgrids.activities` | `start`, `complete`, `fail`, `heartbeat` (task token or run and activity id), `pause`, `unpause`, `reset`, `update_options`, `pause_rules.list\|create\|delete` |
| `fluidgrids.nodes` | `list`, `iterate`, `get(node_type, node_version)`, `list_custom`, `iterate_custom`, `manifest`, `usage_status`, `list_operation_configs`, `iterate_operation_configs`, `get_operation_config`, `list_installations`, `install`, `uninstall`, `set_installation_enabled` |
| `fluidgrids.credentials` | `list`, `iterate`, `get`, `list_types`, `iterate_types`, `create`, `authenticate_with_api_key`, `authenticate_with_basic_auth`, `update`, `delete`, `test` |
| `fluidgrids.webhooks` | `list`, `get`, `create`, `update`, `delete`, `toggle`, `activate`, `deactivate`, `list_deliveries`, `list_all_deliveries`, `iterate_all_deliveries`, `retry_delivery`, `list_filters` |
| `fluidgrids.scheduled_jobs` | `list`, `iterate`, `get`, `create`, `update`, `delete`, `set_enabled`, `pause`, `resume`, `restore`, `scheduler_status` |
| `fluidgrids.dashboard` | `summary`, `usage({"start_date", "end_date"})`, `error_analytics` |
| `fluidgrids.search` | `search`, `by_entity_type`, `search_runs` |
| `fluidgrids.admin` | `system_info` |
| `fluidgrids.variables` | `list`, `get`, `create`, `update`, `delete`, `reveal` |
| `fluidgrids.data_tables` | `list`, `iterate`, `get`, `create`, `update`, `delete`, `query_rows`, `iterate_rows`, `insert_row`, `update_row`, `delete_rows` |
| `fluidgrids.static_data` | `get`, `list`, `reset` |
| `fluidgrids.pinned_data` | `pin`, `unpin` |
| `fluidgrids.tool_approvals` | `list_pending`, `iterate_pending`, `get`, `decide` |
| `fluidgrids.log_streams` | `list`, `get`, `create`, `update`, `delete`, `test` |
| `fluidgrids.secrets_providers` | `list`, `save`, `test_connection` |
| `fluidgrids.tags` | `search`, `list_available`, `create`, `list_for_entity`, `replace_for_entity`, `tag_entity`, `untag_entity` |
| `fluidgrids.usage` | `time_series`, `detailed_node_usage`, `workflow_usage_summary` |

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.

### Following a run

`runs.watch`, `runs.watch_node_states` and `runs.stream_logs` are async iterators over
the run's subscriptions. Each one reads the run over HTTP first, so a run that has
already finished ends the loop without opening a socket, and the events are an
accelerator on top of a poll (every 5 s by default), so a dropped socket costs time
and not updates. A run that ended as `FAILED` is a final update (the loop ends
normally; `runs.result` is the call that raises). Leaving the loop, cancelling the
task or `timeout` close the socket.

```python
async for update in sdk.fluidgrids.runs.watch(run.run_id, timeout=600):
    print(update.status, update.progress)
async for line in sdk.fluidgrids.runs.stream_logs(run.run_id):
    print(line.level, line.message)
```

Subscriptions need the optional `websockets` package: `pip install
"fluidgrids-sdk[subscriptions]"` (it is loaded when a stream first needs a socket;
without it a stream fails with an error that names it, and every other call is
unaffected). An `https` gateway is used as `wss`: with an `http` endpoint the tokens
travel in clear text, so use `http` only for a local test gateway.

### Paging through a list

The `iterate*` methods walk a list page by page (`page_size` 50, 500 for logs and rows;
`max_items` and `max_pages` end the walk normally; a server that never stops is cut off
after 1000 pages with `PAGINATION_LIMIT`):

```python
async for run in sdk.fluidgrids.runs.iterate({"workflow_key": "invoice-sync"}, page_size=100):
    print(run.id, run.status)
```

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

### Run control: updates, queries, reset, batches and activities

With the `fluidgrids.run-control` feature on the workspace, a durable run can be
asked questions, sent updates, reset and operated on in batches, and an activity
that waits for an asynchronous completion can be finished from outside the run:

```python
started = await sdk.fluidgrids.workflows.start_with_update(
    "order-saga", {"name": "add_item", "args": {"sku": "A1"}}, workflow_id="order-7"
)
progress = await sdk.fluidgrids.runs.query(started.run.id, "progress")
added = await sdk.fluidgrids.runs.update(started.run.id, "add_item", {"sku": "B2"})
fork = await sdk.fluidgrids.runs.reset(started.run.id, reason="hotfix deployed")
await sdk.fluidgrids.runs.batch.start(
    "SIGNAL",
    filter={"workflow_key": "order-saga", "status": "RUNNING"},
    payload={"signal_name": "expedite"},
    reason="carrier delay",
)
await sdk.fluidgrids.activities.complete(task_token, {"approved": True})
```

`workflows.start` also takes `task_queue`, `fairness_key` and `fairness_weight`;
a self-hosted queue needs `fluidgrids.self-hosted-workers`. Without the feature
the service answers each of these with `FEATURE_DISABLED`; calls without them
behave as before.

### Standalone activities

With `fluidgrids.standalone-activities` on the workspace, one node operation runs
as a durable activity, with retries, timeouts, heartbeats and an event history
(the service runs it as a durable run of the read-only system workflow
`system-standalone-activity`):

```python
started = await sdk.fluidgrids.activities.start(
    {
        "node_type": "internal:http",
        "operation": "request",
        "args": {"url": "https://example.com/hook", "method": "POST"},
        "retry": {"maximum_attempts": 3, "initial_interval": "1s"},
        "start_to_close_timeout": "30s",
        "idempotency_key": "hook-2026-10-30",
    }
)
output = await sdk.fluidgrids.runs.result(started.run.id)
```

The arguments are literal values (never template-evaluated, never encoded by the
payload codec); routing nodes such as `internal:if` are refused with
`durable.activityTypeNotAllowed`. A repeated `idempotency_key` from the same caller
returns the run it started (`existing` is true; needs `fluidgrids.durable-parity`).
Without the feature the service answers with `FEATURE_DISABLED`.

### Payload codec and converter

Pass `codec=` (encryption, compression) and/or `payload_converter=` (values that
are not JSON) to `FluidGridsSDK`. The client then encodes the payloads it sends
(workflow input, signal payloads, update and query arguments, activity results,
failure details, heartbeat details) and decodes the ones it reads (run output,
update results, query answers, history events). Ids, names, the memo and search
attributes stay in clear text, and no platform token is given to the codec.

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