barbara-api-sdk 0.1.0__tar.gz

barbara_api_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Type check
+        run: mypy
+      - name: Test
+        run: pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build package
+        run: |
+          pip install build
+          python -m build

barbara_api_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build package
+        run: |
+          pip install build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # required for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

barbara_api_sdk-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.env

barbara_api_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.1.0] - 2026-08-06
+
+### Added
+
+- `BarbaraClient` and `AsyncBarbaraClient`, with OAuth2 password-grant authentication, automatic token refresh, and 401 retry.
+- `client.devices`: lifecycle (`list`, `get`, `resolve`, `delete`), secrets, app configuration, docker credentials, and actions (`reboot`, `poweroff`, `provision`, `deprovision`, `brick`).
+- `client.devices.workloads`: create, update, start, stop, logs, app configuration, and container info for device workloads.
+- `client.clusters`: lifecycle (`list`, `get`, `update`, `delete`), secrets, app configuration, and docker credentials.
+- `client.clusters.stacks`: create, update, delete, logs, and app configuration for cluster stacks.
+- `client.applications`: application and application version CRUD, with `multipart/form-data` file uploads.
+- `client.models`: model and model version CRUD, with `multipart/form-data` file uploads.
+- `client.appconfig`: reusable application configuration CRUD.
+- `client.groups`: device group CRUD.
+- `client.users`: read-only user listing and pagination.
+- `client.alerts`: alert listing, acknowledgement, and alert events.
+- `client.api_version()`.
+- Typed exceptions: `BarbaraApiError`, `BarbaraAuthError`, `BarbaraNotFoundError`, `BarbaraPermissionError`.
+- Full test suite using `respx` HTTP mocking.

barbara_api_sdk-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+## Setup
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src tests
+mypy
+```
+
+## Adding a resource
+
+Follow the pattern in `src/barbara/resources/devices.py`:
+
+1. Add or extend the dataclass in `models.py` (only fields the SDK actually uses; keep `.raw` for the original payload).
+2. Add a `resources/<name>.py` with a sync `<Name>Resource` and an async `Async<Name>Resource`, both taking the client in `__init__` and calling `client.request(...)`.
+3. Wire both into `BarbaraClient` and `AsyncBarbaraClient` in `client.py`.
+4. Add tests under `tests/` mocking HTTP with `respx`. Never call the real API in tests.
+5. Verify request/response shapes against the [Barbara API documentation](https://prod.bap.barbara.tech/documentation/) before assuming fields or paths.
+
+## Known gaps
+
+The following are not yet implemented, either because the API does not document a request body for them, or because their shape does not fit the `list`/`get`/`create`/`update`/`delete` pattern used elsewhere in this SDK:
+
+- Device network configuration sub-resources (hostname, network interfaces, iptables, NTP, proxy, VPN).
+- Cluster creation and device cluster-membership management.
+- Model-type workloads and stacks, and their service configuration endpoints.
+- Updating an application version (`PUT` on an app version).
+
+## Checklist before opening a PR
+
+- [ ] Sync and async resources expose the same methods.
+- [ ] New or changed public methods are typed and exported from `barbara/__init__.py` if user-facing.
+- [ ] Tests added or updated; `pytest` passes.
+- [ ] `ruff check` and `mypy` pass.
+- [ ] README updated if the change affects usage.

barbara_api_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Barbara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+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.

barbara_api_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: barbara-api-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Barbara Edge AI platform API
+Project-URL: Homepage, https://github.com/Barbaraedge/barbara-api-sdk-python
+Project-URL: Documentation, https://github.com/Barbaraedge/barbara-api-sdk-python#readme
+Project-URL: Issues, https://github.com/Barbaraedge/barbara-api-sdk-python/issues
+Project-URL: Changelog, https://github.com/Barbaraedge/barbara-api-sdk-python/blob/main/CHANGELOG.md
+Author-email: Barbara <support@barbara.tech>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,barbara,edge-ai,iot,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Barbara API SDK for Python
+
+Official Python SDK for the [Barbara](https://barbara.tech) Edge AI platform API. It provides a typed, synchronous and asynchronous client for managing devices, clusters, applications, models, and related resources.
+
+## Requirements
+
+- Python 3.9 or later
+
+## Installation
+
+```bash
+pip install barbara-api-sdk
+```
+
+## Authentication
+
+The SDK authenticates against the Barbara API using OAuth2 password grant. You need four credentials, referred to as **Barbara API Credentials**:
+
+| Credential | Description |
+|---|---|
+| `BBR_API_USERNAME` | Your Barbara Panel username |
+| `BBR_API_PASSWORD` | Your Barbara Panel password |
+| `BBR_API_CLIENT_ID` | OAuth2 client ID, provided by Barbara |
+| `BBR_API_CLIENT_SECRET` | OAuth2 client secret, provided by Barbara |
+
+Panel credentials can be created at [onboarding.barbara.tech](https://onboarding.barbara.tech). Client credentials are issued by Barbara support (support@barbara.tech).
+
+By default, the client reads credentials from environment variables:
+
+```bash
+export BBR_API_USERNAME="..."
+export BBR_API_PASSWORD="..."
+export BBR_API_CLIENT_ID="..."
+export BBR_API_CLIENT_SECRET="..."
+```
+
+```python
+from barbara import BarbaraClient
+
+client = BarbaraClient.from_env()
+```
+
+Additional optional environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `BBR_API_URL` | Barbara API base URL | `https://prod.bap.barbara.tech` |
+| `BBR_AUTH_URL` | Barbara auth server base URL | `https://prod.auth.barbara.tech/auth` |
+| `BBR_REALM` | Keycloak realm | `bbr_prod` |
+
+Credentials can also be supplied explicitly instead of through environment variables:
+
+```python
+from barbara import BarbaraClient, BarbaraConfig
+
+config = BarbaraConfig(
+    client_id="...",
+    client_secret="...",
+    username="...",
+    password="...",
+)
+client = BarbaraClient(config)
+```
+
+## Quick start
+
+```python
+from barbara import BarbaraClient
+
+with BarbaraClient.from_env() as client:
+    for device in client.devices.list():
+        print(device.device_name, device.status)
+
+    device = client.devices.resolve("my-device-01")
+```
+
+### Async usage
+
+`AsyncBarbaraClient` mirrors `BarbaraClient` method for method; only `await` differs.
+
+```python
+import asyncio
+from barbara import AsyncBarbaraClient
+
+async def main():
+    async with AsyncBarbaraClient.from_env() as client:
+        devices = await client.devices.list()
+
+asyncio.run(main())
+```
+
+## Usage
+
+### Devices
+
+```python
+devices = client.devices.list(search="sensor")
+device = client.devices.get("<device-id>")
+device = client.devices.resolve("my-device-01")  # look up by device name
+
+client.devices.reboot("<device-id>")
+client.devices.poweroff("<device-id>")
+```
+
+#### Device secrets
+
+```python
+client.devices.create_secrets("<device-id>", {"wifi-psk": "s3cr3t"})
+secrets = client.devices.list_secrets("<device-id>")
+client.devices.delete_secret("<device-id>", "<secret-id>")
+```
+
+#### Device app configuration
+
+```python
+client.devices.set_appconfig("<device-id>", config={"threshold": 5})
+config = client.devices.get_appconfig("<device-id>")
+```
+
+#### Docker credentials
+
+```python
+client.devices.create_docker_credentials(
+    "<device-id>", [{"user": "bob", "password": "s3cr3t", "server": "docker.io"}]
+)
+```
+
+### Device workloads
+
+Deploy and manage applications running on a device.
+
+```python
+client.devices.workloads.create_user_workload(
+    "<device-id>",
+    app_version_id="<app-version-id>",
+    application_id="<application-id>",
+)
+
+client.devices.workloads.create_market_workload(
+    "<device-id>",
+    app_version_id="<app-version-id>",
+    application_id="<application-id>",
+    name="my-workload",
+    services=[{"name": "modelservice", "ports": {"PORT_NUMBER": "9083"}}],
+)
+
+client.devices.workloads.start("<device-id>", "<workload-id>")
+client.devices.workloads.stop("<device-id>", "<workload-id>")
+logs = client.devices.workloads.get_logs("<device-id>", "<workload-id>")
+```
+
+Creation and update calls do not return the resulting workload state; call `client.devices.workloads.get(...)` afterwards if you need it.
+
+### Clusters
+
+```python
+clusters = client.clusters.list()
+cluster = client.clusters.get("<cluster-id>")
+client.clusters.update("<cluster-id>", "new-name")
+
+client.clusters.create_secrets("<cluster-id>", {"db-password": "s3cr3t"})
+client.clusters.set_appconfig("<cluster-id>", config={"threshold": 5})
+```
+
+### Cluster stacks
+
+The cluster-level equivalent of device workloads — deploy an application across every device in a cluster.
+
+```python
+client.clusters.stacks.create_user_stack(
+    "<cluster-id>",
+    app_version_id="<app-version-id>",
+    application_id="<application-id>",
+)
+
+client.clusters.stacks.delete("<cluster-id>", "<stack-id>")
+```
+
+### Applications
+
+```python
+apps = client.applications.list()
+
+client.applications.create(
+    "edge-app", "Long description", "Barbara", docker=True, icon_path="./icon.png"
+)
+
+client.applications.create_version(
+    "<application-id>", "./app-v1.tar", "1.0.0", ["amd64"], ["Initial release"]
+)
+```
+
+`create` and `create_version` upload files (icon, installable artifact) as `multipart/form-data`. Pass a local file path; the SDK reads the file and builds the request.
+
+### Models
+
+```python
+models = client.models.list()
+
+client.models.create(
+    "anomaly-detector", "Long description", "Barbara", model_type=0, engine=0
+)
+
+client.models.create_version("<model-id>", "./model.onnx", "1.0.0", ["Initial release"])
+```
+
+`sha256` and `size` for a model version are computed automatically from the artifact.
+
+### App configurations
+
+Reusable, named application configurations that can be referenced by ID elsewhere in the API.
+
+```python
+app_config = client.appconfig.create(
+    name="sensor-thresholds",
+    description="Per-device alert thresholds",
+    config={"temperature_max": 80},
+)
+```
+
+### Groups
+
+```python
+group = client.groups.create(
+    name="floor-2-sensors",
+    description="All floor 2 devices",
+    device_ids=["<device-id-1>", "<device-id-2>"],
+)
+```
+
+### Users
+
+```python
+users = client.users.list()
+page = client.users.paginate(offset=0, size=50)
+```
+
+### Alerts
+
+```python
+alerts = client.alerts.list()
+client.alerts.ack("<alert-id>")
+events = client.alerts.list_events(device_id="<device-id>")
+```
+
+## Error handling
+
+All API errors raise a subclass of `BarbaraApiError`:
+
+```python
+from barbara import BarbaraApiError, BarbaraAuthError, BarbaraNotFoundError, BarbaraPermissionError
+
+try:
+    client.devices.resolve("unknown-device")
+except BarbaraNotFoundError:
+    ...
+except BarbaraPermissionError:
+    ...
+except BarbaraApiError as e:
+    print(e.status, e.body)
+```
+
+## Design
+
+- **One client, one resource tree.** `BarbaraClient` and `AsyncBarbaraClient` expose the same resources (`.devices`, `.clusters`, `.applications`, ...) with identical method signatures.
+- **Automatic token refresh.** A request that receives a 401 is retried once with a freshly fetched token.
+- **Lightweight typed models.** Response entities are plain dataclasses, not a heavyweight validation layer. Every entity keeps the original API payload in `.raw`.
+- **Typed exceptions.** `BarbaraNotFoundError`, `BarbaraAuthError`, and `BarbaraPermissionError` subclass `BarbaraApiError` so callers can handle specific failure modes.
+
+## API reference
+
+| Resource | Description |
+|---|---|
+| `client.devices` | Device lifecycle, secrets, app configuration, docker credentials, and actions (reboot, provision, ...) |
+| `client.devices.workloads` | Applications deployed on a device |
+| `client.clusters` | Cluster lifecycle, secrets, app configuration, and docker credentials |
+| `client.clusters.stacks` | Applications deployed across a cluster |
+| `client.applications` | Application catalog and versions |
+| `client.models` | Model catalog and versions |
+| `client.appconfig` | Reusable application configurations |
+| `client.groups` | Device groups |
+| `client.users` | Company users (read-only) |
+| `client.alerts` | Alerts and alert events |
+
+See each resource module's docstrings, or the [Barbara API documentation](https://prod.bap.barbara.tech/documentation/), for the full method reference.
+
+## Roadmap
+
+The following areas of the Barbara API are not yet covered by this SDK:
+
+- Device network configuration (interfaces, NTP, proxy, VPN)
+- Cluster creation and device cluster-membership management
+- Model-type workloads and stacks
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). For the release process, see [RELEASING.md](RELEASING.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).