Metadata-Version: 2.4
Name: datafuse-sdk
Version: 1.0.0
Summary: Python SDK for the Datafuse Platform API (v1)
Author-email: Datafuse Support <support@datafuse.xyz>
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: urllib3<3.0.0,>=1.25.3
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.7.1

# Datafuse Platform Python SDK

[![PyPI version](https://img.shields.io/pypi/v/datafuse.svg?style=flat-square)](https://pypi.org/project/datafuse/)
[![License](https://img.shields.io/badge/license-Proprietary-blue.svg?style=flat-square)](#license)

The official **Datafuse Platform Python SDK** provides a type-safe, developer-friendly interface to integrate and execute secure API tools flatly into your Python apps.

Compatible with Python 3.8+, featuring comprehensive IDE autocompletion, synchronous client architecture, and robust PEP-517 compliance.

---

## Installation

Install directly from your local project repository during development:

```bash
pip install -e sdks/python
```

Or from a private package repository:

```bash
pip install datafuse
```

---

## Getting Started

Initialize the unified client using your platform API Key. The client handles authorization, user-agent injection, and exposes sub-client APIs on a flat model.

```python
from datafuse import Datafuse

sdk = Datafuse(
    api_key="df_live_your_api_key_here"
)
```

### Overriding Base URLs (Enterprise Private VPC Override)

If you are developing locally or executing within private enterprise clouds/VPC environments, you can override the target address:

```python
sdk = Datafuse(
    api_key="df_local_secret",
    base_url="https://datafuse.your-enterprise-vpc.internal/api"
)
```

---

## Code Examples

### 1. Browse providers, tools and triggers (public)

These endpoints require no API key.

```python
from datafuse import Datafuse

sdk = Datafuse()

# List every provider (paginated: .items / .total / .page / .page_size)
page = sdk.providers.list_providers_api_v1_providers_get()
for p in page.items:
    print(f"{p.key:20s} {p.title} ({p.tools_count} tools, {p.triggers_count} triggers)")

# Inspect a provider's tools and triggers (each is a list of dicts)
tools = sdk.providers.get_provider_tools_api_v1_providers_key_tools_get("slack")
triggers = sdk.providers.get_provider_triggers_api_v1_providers_key_triggers_get("slack")
print(f"slack: {len(tools)} tools, {len(triggers)} triggers")
for tr in triggers:
    print(f"  {tr['slug']:35s} {tr['name']}")
```

### 2. Running Remote Tool Execution

Invoke a tool through one of your integrations.

```python
from datafuse import Datafuse
from datafuse.generated import IntegrationInvokeRequest

sdk = Datafuse(api_key="your_api_key")

try:
    req = IntegrationInvokeRequest(
        tool_key="slack_send_message",
        arguments={
            "channel": "#alerts-production",
            "text": "🚨 Critical Alert: System health checks completed successfully."
        }
    )
    result = sdk.integrations.invoke_tool_api_v1_integrations_id_invoke_post(
        id="3c8d9e2b-23f4-4b5c-897d-1234567890ab",
        integration_invoke_request=req,
    )
    print(f"Action Output Payload: {result}")

except Exception as e:
    print(f"Execution Failed: {e}")
```

### 3. Compliance Audit Logs

```python
from datafuse import Datafuse
from datafuse.generated import AuditLogCreate

sdk = Datafuse(api_key="your_api_key")

sdk.compliance_audit_logs.create_audit_log_api_v1_audit_logs_post(
    audit_log_create=AuditLogCreate(
        action="toolkit.install",
        resource_type="toolkit",
        resource_id="slack",
        metadata_json={"author": "admin", "ip": "127.0.0.1"},
    )
)
logs = sdk.compliance_audit_logs.list_audit_logs_api_v1_audit_logs_get()
for log in logs:
    print(f"- {log}")
```

---

## Client Organization

The high-level `Datafuse` class exposes a flat namespace of sub-clients, discovered
dynamically from the generated package so it always matches the current API spec.
Each method maps 1:1 to a v1 endpoint:

* **`.providers`** — list providers/categories, fetch a provider's tools and triggers, manage custom providers.
* **`.integrations`** — create integrations and invoke/resolve/test tools.
* **`.connected_accounts`** — connect, list and disconnect accounts.
* **`.playground`** — chat threads and streaming.
* **`.authentication`** — login, register, refresh, `/auth/me`.
* **`.api_keys`** — create, list and delete API keys.
* **`.organizations`**, **`.billing`**, **`.oauth`** (`o_auth`), **`.compliance_audit_logs`** — account, billing, OAuth and audit operations.

> Method names are generated from the spec's `operationId` (e.g.
> `providers.get_provider_triggers_api_v1_providers_key_triggers_get`). Use your
> IDE's autocompletion on each sub-client to discover them.

### Authentication

The key you pass is wired into both security schemes the API declares —
`Authorization: Bearer <key>` (OAuth2) and `x-api-key: <key>` — so every endpoint
receives the right credential automatically.

---

## License

Proprietary © [Datafuse](https://datafuse.xyz). All rights reserved.
