crowddrop-sdk 0.1.0__tar.gz

crowddrop_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: crowddrop-sdk
+Version: 0.1.0
+Summary: CrowdDrop's SDK for embodied-agent hardware. This release covers cloud_brain: the LLM stays in the cloud, the device is a thin actuator/sensor bridge over Pub/Sub.
+Project-URL: Repository, https://github.com/crowddrop-ai/crowddrop_ai_agents
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: cloud-brain
+Requires-Dist: crowddrop-pubsub-sdk<1.0.0,>=0.2.0; extra == "cloud-brain"
+Requires-Dist: requests<3.0.0,>=2.28.0; extra == "cloud-brain"
+Requires-Dist: google-auth<3.0.0,>=2.29.0; extra == "cloud-brain"
+
+# crowddrop-sdk
+
+CrowdDrop's SDK for connecting embodied-agent hardware to the CrowdDrop
+platform. It splits into two architecturally different scenarios:
+
+- **`cloud_brain`** (this release) - the LLM/tool-calling brain stays in
+  CrowdDrop's cloud backend; your device is a thin actuator/sensor bridge
+  over Google Cloud Pub/Sub. This is the right choice if your hardware can't
+  run an LLM locally but can run a real Python process.
+- **`edge_brain`** (planned, not yet released) - the LLM itself runs on your
+  device. A different SDK surface entirely, for hardware with real local
+  inference capacity.
+
+If you're building a companion-computer-class device (e.g. Raspberry-Pi
+class, full Linux + Python) that receives commands and reports telemetry,
+you want the `cloud-brain` extra:
+
+```bash
+pip install "crowddrop-sdk[cloud-brain]"
+```
+
+This pulls in `crowddrop-pubsub-sdk` (CrowdDrop's Pub/Sub transport library)
+as its only dependency - nothing else, so it stays light on constrained
+hardware. The base `crowddrop-sdk` install (no extra) has no dependencies at
+all.
+
+## Getting credentials
+
+There's no self-service signup. CrowdDrop issues one **agent device key**
+per physical device, tied to the persona it embodies, and hands it to you
+out-of-band along with the URL of the backend's token-vending endpoint. If
+you don't have both yet, ask whoever set up your CrowdDrop persona - there's
+no dashboard to generate one yourself. Your device never handles a raw GCP
+service-account key file: it trades its device key for a short-lived GCP
+access token by calling the token-vending endpoint (see
+`cloud_brain/drone/edge_agent.py`'s `fetch_gcp_access_token`), and refreshes
+that token automatically as it nears expiry.
+
+## API reference (`cloud_brain`)
+
+- **`crowddrop_sdk.cloud_brain.events.DRONE_COMMANDS`** - the eight
+  supported movement primitives, each a fixed pulse with no
+  duration/distance parameter: `take_off`, `land`, `forward`, `backward`,
+  `strafe_left`, `strafe_right`, `turn_left`, `turn_right`.
+- **`DroneCommandEvent(drone_id, command, issued_at, sequence)`** - what you
+  receive, one per command.
+- **`DroneTelemetryEvent(drone_id, latitude, longitude, heading,
+  battery_level, reported_at, sequence)`** - what you publish back.
+- **`crowddrop_sdk.cloud_brain.drone.channels.DroneCommandSubscriber`** -
+  pull-based subscriber for commands (you always initiate the connection
+  outward - nothing is ever pushed to your device).
+- **`crowddrop_sdk.cloud_brain.drone.channels.DroneTelemetryPublisher`** -
+  publisher for telemetry, with a `publish_telemetry(drone_id, latitude,
+  longitude, heading, battery_level)` convenience method.
+- **Two integration points you implement** - `handle_command(event)` (map
+  each command to your real flight-controller call) and
+  `read_battery_and_gps()` (return a real sensor reading). Both are stand-ins
+  in the example below; this SDK doesn't know your hardware's API.
+
+## Quickstart
+
+See [`cloud_brain/drone/README.md`](crowddrop_sdk/cloud_brain/drone/README.md)
+for a runnable example (`edge_agent.py`) and the exact env vars it needs.
+
+## Releasing (publishing a new version to PyPI)
+
+Releases are tag-triggered via `.github/workflows/publish-crowddrop-sdk.yml`,
+using PyPI's **Trusted Publishing** (OIDC) — no API token is stored as a
+GitHub secret.
+
+1. Bump `version` in `crowddrop_sdk/pyproject.toml`.
+2. Commit that change (on a branch, via the normal PR flow).
+3. Once merged, tag the merge commit and push the tag:
+   ```bash
+   git tag crowddrop-sdk-v<version>   # e.g. crowddrop-sdk-v0.1.1
+   git push origin crowddrop-sdk-v<version>
+   ```
+   The tag push is what fires the workflow — it builds `crowddrop_sdk/` and
+   uploads it to [pypi.org/project/crowddrop-sdk](https://pypi.org/project/crowddrop-sdk/).
+   No other trigger publishes this package.
+
+If `cloud-brain`'s dependency on `crowddrop-pubsub-sdk` (see `pyproject.toml`)
+needs bumping too, release `pubsub_sdk` first — see its own README's
+"Releasing" section, same mechanism, separate workflow/tag prefix
+(`pubsub-sdk-v*`).
+
+**One-time setup, not yet done as of this writing — needed before the first
+tag push, and again only if this ever moves to a different PyPI
+account/org:**
+- Register a **pending publisher** for `crowddrop-sdk` at
+  https://pypi.org/manage/account/publishing/ — this can be done before the
+  PyPI project exists, so it covers the *first-ever* release too, not just
+  subsequent ones. Fill in: PyPI project name `crowddrop-sdk`, repo owner
+  `crowddrop-ai`, repo name `crowddrop_ai_agents`, workflow filename
+  `publish-crowddrop-sdk.yml`, environment name `pypi`. Requires a PyPI
+  account with 2FA enabled — no API token to generate or store.
+- The `pypi` GitHub Environment referenced by the workflow is created
+  automatically the first time the workflow runs against it; create it
+  manually in this repo's Settings → Environments beforehand only if you
+  want a required-reviewer protection rule (so a tag push pauses for human
+  approval before it actually publishes).
+- `../scripts/publish_python_packages.sh` (manual `build` + `twine upload`)
+  is kept as a fallback/local-dry-run tool only — with a pending publisher
+  registered, it's no longer needed even for the first release.
+
+Versioning is manual — nothing cross-checks the tag against
+`pyproject.toml`'s `version`. Bump the file first, commit, *then* tag that
+exact commit; tagging a commit whose `pyproject.toml` still has an
+already-published version will fail the upload (PyPI rejects re-uploading an
+existing version).

crowddrop_sdk-0.1.0/README.md

@@ -0,0 +1,110 @@
+# crowddrop-sdk
+
+CrowdDrop's SDK for connecting embodied-agent hardware to the CrowdDrop
+platform. It splits into two architecturally different scenarios:
+
+- **`cloud_brain`** (this release) - the LLM/tool-calling brain stays in
+  CrowdDrop's cloud backend; your device is a thin actuator/sensor bridge
+  over Google Cloud Pub/Sub. This is the right choice if your hardware can't
+  run an LLM locally but can run a real Python process.
+- **`edge_brain`** (planned, not yet released) - the LLM itself runs on your
+  device. A different SDK surface entirely, for hardware with real local
+  inference capacity.
+
+If you're building a companion-computer-class device (e.g. Raspberry-Pi
+class, full Linux + Python) that receives commands and reports telemetry,
+you want the `cloud-brain` extra:
+
+```bash
+pip install "crowddrop-sdk[cloud-brain]"
+```
+
+This pulls in `crowddrop-pubsub-sdk` (CrowdDrop's Pub/Sub transport library)
+as its only dependency - nothing else, so it stays light on constrained
+hardware. The base `crowddrop-sdk` install (no extra) has no dependencies at
+all.
+
+## Getting credentials
+
+There's no self-service signup. CrowdDrop issues one **agent device key**
+per physical device, tied to the persona it embodies, and hands it to you
+out-of-band along with the URL of the backend's token-vending endpoint. If
+you don't have both yet, ask whoever set up your CrowdDrop persona - there's
+no dashboard to generate one yourself. Your device never handles a raw GCP
+service-account key file: it trades its device key for a short-lived GCP
+access token by calling the token-vending endpoint (see
+`cloud_brain/drone/edge_agent.py`'s `fetch_gcp_access_token`), and refreshes
+that token automatically as it nears expiry.
+
+## API reference (`cloud_brain`)
+
+- **`crowddrop_sdk.cloud_brain.events.DRONE_COMMANDS`** - the eight
+  supported movement primitives, each a fixed pulse with no
+  duration/distance parameter: `take_off`, `land`, `forward`, `backward`,
+  `strafe_left`, `strafe_right`, `turn_left`, `turn_right`.
+- **`DroneCommandEvent(drone_id, command, issued_at, sequence)`** - what you
+  receive, one per command.
+- **`DroneTelemetryEvent(drone_id, latitude, longitude, heading,
+  battery_level, reported_at, sequence)`** - what you publish back.
+- **`crowddrop_sdk.cloud_brain.drone.channels.DroneCommandSubscriber`** -
+  pull-based subscriber for commands (you always initiate the connection
+  outward - nothing is ever pushed to your device).
+- **`crowddrop_sdk.cloud_brain.drone.channels.DroneTelemetryPublisher`** -
+  publisher for telemetry, with a `publish_telemetry(drone_id, latitude,
+  longitude, heading, battery_level)` convenience method.
+- **Two integration points you implement** - `handle_command(event)` (map
+  each command to your real flight-controller call) and
+  `read_battery_and_gps()` (return a real sensor reading). Both are stand-ins
+  in the example below; this SDK doesn't know your hardware's API.
+
+## Quickstart
+
+See [`cloud_brain/drone/README.md`](crowddrop_sdk/cloud_brain/drone/README.md)
+for a runnable example (`edge_agent.py`) and the exact env vars it needs.
+
+## Releasing (publishing a new version to PyPI)
+
+Releases are tag-triggered via `.github/workflows/publish-crowddrop-sdk.yml`,
+using PyPI's **Trusted Publishing** (OIDC) — no API token is stored as a
+GitHub secret.
+
+1. Bump `version` in `crowddrop_sdk/pyproject.toml`.
+2. Commit that change (on a branch, via the normal PR flow).
+3. Once merged, tag the merge commit and push the tag:
+   ```bash
+   git tag crowddrop-sdk-v<version>   # e.g. crowddrop-sdk-v0.1.1
+   git push origin crowddrop-sdk-v<version>
+   ```
+   The tag push is what fires the workflow — it builds `crowddrop_sdk/` and
+   uploads it to [pypi.org/project/crowddrop-sdk](https://pypi.org/project/crowddrop-sdk/).
+   No other trigger publishes this package.
+
+If `cloud-brain`'s dependency on `crowddrop-pubsub-sdk` (see `pyproject.toml`)
+needs bumping too, release `pubsub_sdk` first — see its own README's
+"Releasing" section, same mechanism, separate workflow/tag prefix
+(`pubsub-sdk-v*`).
+
+**One-time setup, not yet done as of this writing — needed before the first
+tag push, and again only if this ever moves to a different PyPI
+account/org:**
+- Register a **pending publisher** for `crowddrop-sdk` at
+  https://pypi.org/manage/account/publishing/ — this can be done before the
+  PyPI project exists, so it covers the *first-ever* release too, not just
+  subsequent ones. Fill in: PyPI project name `crowddrop-sdk`, repo owner
+  `crowddrop-ai`, repo name `crowddrop_ai_agents`, workflow filename
+  `publish-crowddrop-sdk.yml`, environment name `pypi`. Requires a PyPI
+  account with 2FA enabled — no API token to generate or store.
+- The `pypi` GitHub Environment referenced by the workflow is created
+  automatically the first time the workflow runs against it; create it
+  manually in this repo's Settings → Environments beforehand only if you
+  want a required-reviewer protection rule (so a tag push pauses for human
+  approval before it actually publishes).
+- `../scripts/publish_python_packages.sh` (manual `build` + `twine upload`)
+  is kept as a fallback/local-dry-run tool only — with a pending publisher
+  registered, it's no longer needed even for the first release.
+
+Versioning is manual — nothing cross-checks the tag against
+`pyproject.toml`'s `version`. Bump the file first, commit, *then* tag that
+exact commit; tagging a commit whose `pyproject.toml` still has an
+already-published version will fail the upload (PyPI rejects re-uploading an
+existing version).

crowddrop_sdk-0.1.0/crowddrop_sdk/__init__.py

@@ -0,0 +1,5 @@
+"""crowddrop-sdk: CrowdDrop's SDK for embodied-agent hardware. See
+crowddrop_sdk.cloud_brain for this release's cloud-brain scenario (import
+that submodule directly - the base install here declares no dependencies, so
+nothing cloud_brain-specific is re-exported at this top level).
+"""

crowddrop_sdk-0.1.0/crowddrop_sdk/cloud_brain/__init__.py

@@ -0,0 +1,13 @@
+"""cloud_brain: the LLM/tool-calling brain stays in the cloud, the device is
+a thin actuator/sensor bridge over Google Cloud Pub/Sub. This submodule ships
+the shared wire contract (events.py) and the drone's own client classes
+(drone/channels.py) - the backend's equivalents live outside this published
+package, in the crowddrop_ai_agents repo itself.
+"""
+from .events import DRONE_COMMANDS, DroneCommandEvent, DroneTelemetryEvent
+
+__all__ = [
+    "DRONE_COMMANDS",
+    "DroneCommandEvent",
+    "DroneTelemetryEvent",
+]

crowddrop_sdk-0.1.0/crowddrop_sdk/cloud_brain/drone/__init__.py

@@ -0,0 +1,3 @@
+"""The physical drone's own client classes (channels.py) and runnable
+example (edge_agent.py) - see this directory's README.md.
+"""

crowddrop_sdk-0.1.0/crowddrop_sdk/cloud_brain/drone/channels.py

@@ -0,0 +1,88 @@
+"""The physical drone's own pub/sub classes - imported only by edge_agent.py
+(and whatever real edge code eventually replaces/extends it). The backend's
+equivalents (DroneCommandPublisher, DroneTelemetrySubscriber) live in
+fastapi/app/first_citizen_drone/channels.py instead, outside this published
+package - nothing outside that repo ever uses them.
+
+Both classes are thin GenericPublisher/GenericSubscriber subclasses
+(pubsub_sdk.client) - a subclass fixes the topic/subscription ids and message
+type; everything else (client construction, degrade-gracefully behavior,
+emulator-only auto-create, ack/nack) lives there once.
+"""
+import datetime
+import itertools
+import logging
+import os
+from typing import Optional
+
+from pubsub_sdk import PubSubConfig
+from pubsub_sdk.client import GenericPublisher, GenericSubscriber
+
+from ..events import DroneCommandEvent, DroneTelemetryEvent
+
+logger = logging.getLogger(__name__)
+
+DRONE_COMMAND_TOPIC_ID_ENV = "DRONE_COMMAND_TOPIC_ID"
+DRONE_COMMAND_SUBSCRIPTION_ID_ENV = "DRONE_COMMAND_SUBSCRIPTION_ID"
+DRONE_TELEMETRY_TOPIC_ID_ENV = "DRONE_TELEMETRY_TOPIC_ID"
+
+DEFAULT_DRONE_COMMAND_TOPIC_ID = "drone-command-events"
+DEFAULT_DRONE_COMMAND_SUBSCRIPTION_ID = "drone-command-events-drone"
+DEFAULT_DRONE_TELEMETRY_TOPIC_ID = "drone-telemetry-events"
+
+
+class DroneCommandSubscriber(GenericSubscriber[DroneCommandEvent]):
+    """The drone consumes commands. Pull-based (pull_forever), matching
+    StepEventSubscriber's existing pattern in this org's backend - the drone
+    always initiates the connection outward, never accepts inbound (it's a
+    mobile, likely-NATed device with no static IP).
+
+    One fixed subscription (always_self_provision=False - provisioned ahead
+    of time by infra against real GCP, auto-created only against the
+    emulator), since exactly one physical drone is in scope today. drone_id
+    still rides as a message attribute (see events.py) so a second physical
+    drone can later get its own filter_expr-scoped subscription without a
+    wire-format change.
+    """
+
+    def __init__(self, config: Optional[PubSubConfig] = None):
+        cfg = config or PubSubConfig.from_env()
+        topic_id = os.environ.get(DRONE_COMMAND_TOPIC_ID_ENV, DEFAULT_DRONE_COMMAND_TOPIC_ID)
+        subscription_id = os.environ.get(DRONE_COMMAND_SUBSCRIPTION_ID_ENV, DEFAULT_DRONE_COMMAND_SUBSCRIPTION_ID)
+        super().__init__(
+            config=cfg,
+            topic_id=topic_id,
+            subscription_id=subscription_id,
+            message_cls=DroneCommandEvent,
+            label="DroneCommandSubscriber",
+        )
+
+
+class DroneTelemetryPublisher(GenericPublisher[DroneTelemetryEvent]):
+    """The drone publishes telemetry - real GPS/battery/heading readings, not
+    simulated and not a placeholder."""
+
+    def __init__(self, config: Optional[PubSubConfig] = None):
+        cfg = config or PubSubConfig.from_env()
+        topic_id = os.environ.get(DRONE_TELEMETRY_TOPIC_ID_ENV, DEFAULT_DRONE_TELEMETRY_TOPIC_ID)
+        super().__init__(config=cfg, topic_id=topic_id, label="DroneTelemetryPublisher")
+        self._sequence = itertools.count(start=1)
+
+    def publish_telemetry(
+        self,
+        drone_id: str,
+        latitude: float,
+        longitude: float,
+        heading: float,
+        battery_level: float,
+    ) -> bool:
+        event = DroneTelemetryEvent(
+            drone_id=drone_id,
+            latitude=latitude,
+            longitude=longitude,
+            heading=heading,
+            battery_level=battery_level,
+            reported_at=datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            sequence=next(self._sequence),
+        )
+        return self.publish(event)

crowddrop_sdk-0.1.0/crowddrop_sdk/cloud_brain/drone/edge_agent.py

@@ -0,0 +1,193 @@
+"""Runnable example for the physical drone's companion computer. Shows the
+full loop: fetch a short-lived GCP access token (never a key file - see the
+README next to this file), receive commands, drive the flight controller,
+and report telemetry back.
+
+Two integration points are clearly marked below (handle_command,
+read_battery_and_gps) - this file does not know the real flight-controller
+API and doesn't guess it. Run it as-is against a stand-in (or with
+PUBSUB_EMULATOR_HOST set, against the emulator) to see the wiring work end
+to end before a real flight controller is plugged in.
+"""
+import datetime
+import functools
+import logging
+import os
+import threading
+from dataclasses import dataclass
+
+import google.auth.credentials
+import google.auth.transport.requests
+import requests
+from google.auth import _helpers
+from google.cloud import pubsub_v1
+
+from .channels import DroneCommandSubscriber, DroneTelemetryPublisher
+from ..events import DRONE_COMMANDS, DroneCommandEvent
+
+logger = logging.getLogger(__name__)
+
+DRONE_ID_ENV = "DRONE_ID"
+DRONE_DEVICE_KEY_ENV = "DRONE_DEVICE_KEY"
+BACKEND_TOKEN_VENDING_URL_ENV = "BACKEND_TOKEN_VENDING_URL"
+
+TELEMETRY_HEARTBEAT_SECONDS = 10
+GCP_TOKEN_REFRESH_MARGIN_SECONDS = 300
+
+
+def fetch_gcp_access_token(device_key: str, backend_url: str) -> dict:
+    """POSTs to the backend's token-vending endpoint with the drone's one
+    agent device key and returns {"access_token": ..., "expires_in_seconds":
+    ...}. Never a GCP service-account key file - see this package's own
+    README."""
+    response = requests.post(
+        backend_url,
+        headers={"X-Agent-Device-Key": device_key},
+        timeout=10,
+    )
+    response.raise_for_status()
+    return response.json()
+
+
+class _DeviceKeyCredentials(google.auth.credentials.Credentials):
+    """A google-auth Credentials implementation whose refresh() calls back
+    into this backend's token-vending endpoint with the drone's one agent
+    device key, instead of the usual service-account/user OAuth flow - the
+    drone never handles a GCP service-account key file. The pubsub_v1 client
+    machinery calls refresh() automatically on the next new RPC once the
+    current token is near expiry; _run_token_refresh below additionally
+    refreshes proactively, since a long-lived streaming pull may not open a
+    new RPC before expiry on its own."""
+
+    def __init__(self, device_key: str, backend_url: str):
+        super().__init__()
+        self._device_key = device_key
+        self._backend_url = backend_url
+
+    def refresh(self, request) -> None:
+        token_response = fetch_gcp_access_token(self._device_key, self._backend_url)
+        self.token = token_response["access_token"]
+        self.expiry = _helpers.utcnow() + datetime.timedelta(
+            seconds=token_response.get("expires_in_seconds", 3600)
+        )
+
+
+def _apply_device_key_credentials(device_key: str, backend_url: str) -> "_DeviceKeyCredentials":
+    """Makes every PublisherClient()/SubscriberClient() construction in this
+    process (they're always called with no arguments, relying on ADC - see
+    pubsub_sdk.client.GenericPublisher/GenericSubscriber) use these
+    credentials instead - the same monkeypatch technique
+    scripts/pubsub_smoke_test.py already uses for a plain
+    `gcloud auth print-access-token`, just backed by a refreshable
+    Credentials object here instead of a fixed token. Returns the
+    credentials object so the caller can also refresh it proactively (see
+    _run_token_refresh) - the pubsub client's own lazy on-RPC refresh isn't
+    guaranteed to fire mid-stream on a long-lived streaming pull."""
+    creds = _DeviceKeyCredentials(device_key, backend_url)
+    pubsub_v1.PublisherClient = functools.partial(pubsub_v1.PublisherClient, credentials=creds)
+    pubsub_v1.SubscriberClient = functools.partial(pubsub_v1.SubscriberClient, credentials=creds)
+    return creds
+
+
+def _run_token_refresh(creds: "_DeviceKeyCredentials", stop_event: threading.Event) -> None:
+    """Proactively refreshes creds before they expire, rather than relying
+    solely on the pubsub client's lazy on-RPC refresh - belt-and-suspenders
+    for DroneCommandSubscriber's long-lived streaming pull, which may not
+    reopen (and thus re-authenticate) before the vended token expires."""
+    request = google.auth.transport.requests.Request()
+    while not stop_event.is_set():
+        creds.refresh(request)
+        sleep_seconds = max((creds.expiry - _helpers.utcnow()).total_seconds() - GCP_TOKEN_REFRESH_MARGIN_SECONDS, 1)
+        stop_event.wait(sleep_seconds)
+
+
+def handle_command(event: DroneCommandEvent) -> None:
+    """command -> flight-controller-call dispatch. This is the integration
+    point - wire up the real flight controller here, one branch per command
+    in DRONE_COMMANDS."""
+    if event.command not in DRONE_COMMANDS:
+        logger.error("handle_command: unknown command '%s', ignoring.", event.command)
+        return
+
+    logger.info("handle_command: executing '%s' (sequence=%s)", event.command, event.sequence)
+
+    raise NotImplementedError(f"integration point: wire up the real flight controller here ({event.command})")
+
+
+@dataclass
+class SensorReading:
+    """A raw sensor reading, distinct from DroneTelemetryEvent - this is just
+    what the hardware measured, not yet stamped with drone_id/reported_at/
+    sequence (those are publish_telemetry's job)."""
+
+    latitude: float
+    longitude: float
+    heading: float
+    battery_level: float
+
+
+def read_battery_and_gps() -> SensorReading:
+    """Returns a real GPS/battery/heading reading. Stand-in below returns a
+    fixed reading, for anyone testing without hardware in hand - wire up the
+    real sensors here."""
+    return SensorReading(latitude=0.0, longitude=0.0, heading=0.0, battery_level=100.0)
+
+
+def _publish_telemetry_now(publisher: DroneTelemetryPublisher, drone_id: str) -> None:
+    reading = read_battery_and_gps()
+    publisher.publish_telemetry(
+        drone_id=drone_id,
+        latitude=reading.latitude,
+        longitude=reading.longitude,
+        heading=reading.heading,
+        battery_level=reading.battery_level,
+    )
+
+
+def _run_telemetry_heartbeat(publisher: DroneTelemetryPublisher, drone_id: str, stop_event: threading.Event) -> None:
+    while not stop_event.is_set():
+        _publish_telemetry_now(publisher, drone_id)
+        stop_event.wait(TELEMETRY_HEARTBEAT_SECONDS)
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO)
+
+    drone_id = os.environ[DRONE_ID_ENV]
+    device_key = os.environ.get(DRONE_DEVICE_KEY_ENV)
+    backend_url = os.environ.get(BACKEND_TOKEN_VENDING_URL_ENV)
+
+    stop_event = threading.Event()
+
+    if device_key and backend_url:
+        creds = _apply_device_key_credentials(device_key, backend_url)
+        refresh_thread = threading.Thread(target=_run_token_refresh, args=(creds, stop_event), daemon=True)
+        refresh_thread.start()
+    else:
+        logger.info(
+            "%s/%s not set - assuming ambient credentials (e.g. PUBSUB_EMULATOR_HOST for local testing).",
+            DRONE_DEVICE_KEY_ENV,
+            BACKEND_TOKEN_VENDING_URL_ENV,
+        )
+
+    command_subscriber = DroneCommandSubscriber()
+    telemetry_publisher = DroneTelemetryPublisher()
+
+    def _on_command(event: DroneCommandEvent) -> None:
+        handle_command(event)
+        _publish_telemetry_now(telemetry_publisher, drone_id)
+
+    heartbeat_thread = threading.Thread(
+        target=_run_telemetry_heartbeat, args=(telemetry_publisher, drone_id, stop_event), daemon=True
+    )
+    heartbeat_thread.start()
+
+    try:
+        command_subscriber.pull_forever(_on_command)
+    finally:
+        stop_event.set()
+        command_subscriber.stop()
+
+
+if __name__ == "__main__":
+    main()

crowddrop_sdk-0.1.0/crowddrop_sdk/cloud_brain/events.py

@@ -0,0 +1,89 @@
+"""DroneCommandEvent / DroneTelemetryEvent: the wire contract for CrowdDrop's
+cloud-brain scenario - the LLM/tool-calling brain stays in the cloud, the
+physical device is a thin actuator/sensor bridge over Pub/Sub. Both the
+backend's own channel classes (fastapi/app/first_citizen_drone/channels.py,
+not published) and the drone's (cloud_brain/drone/channels.py, this module's
+sibling) import these two event types - the one thing genuinely shared
+between the two sides of the wire.
+
+Field names and the to_pubsub_message()/from_pubsub_message() shape mirror
+pubsub_sdk's StepEvent (JSON body + string attributes for cheap server-side
+filtering without deserializing) so a developer already familiar with that
+pattern in the CrowdDrop backend recognizes this one immediately.
+"""
+import json
+from dataclasses import asdict, dataclass
+from typing import Dict, Optional, Tuple
+
+DRONE_COMMANDS = (
+    "take_off",
+    "land",
+    "forward",
+    "backward",
+    "strafe_left",
+    "strafe_right",
+    "turn_left",
+    "turn_right",
+)
+
+
+@dataclass
+class DroneCommandEvent:
+    """One fixed-pulse movement primitive, backend -> drone. No duration/
+    distance field on any of the eight commands - take-off always rises to
+    the same default altitude, "a lot" of lateral movement is expressed as
+    repeated messages, not a bigger number."""
+
+    drone_id: str
+    command: str
+    issued_at: str
+    sequence: Optional[int] = None
+
+    def to_pubsub_message(self) -> Tuple[bytes, Dict[str, str]]:
+        body = asdict(self)
+        data = json.dumps(body).encode("utf-8")
+        attributes = {"drone_id": self.drone_id, "command": self.command}
+        return data, attributes
+
+    @classmethod
+    def from_pubsub_message(cls, data: bytes, attributes: Optional[Dict[str, str]] = None) -> "DroneCommandEvent":
+        body = json.loads(data.decode("utf-8"))
+        return cls(
+            drone_id=body["drone_id"],
+            command=body["command"],
+            issued_at=body["issued_at"],
+            sequence=body.get("sequence"),
+        )
+
+
+@dataclass
+class DroneTelemetryEvent:
+    """One real GPS/battery/heading reading, drone -> backend. Real, not
+    simulated and not a placeholder."""
+
+    drone_id: str
+    latitude: float
+    longitude: float
+    heading: float
+    battery_level: float
+    reported_at: str
+    sequence: Optional[int] = None
+
+    def to_pubsub_message(self) -> Tuple[bytes, Dict[str, str]]:
+        body = asdict(self)
+        data = json.dumps(body).encode("utf-8")
+        attributes = {"drone_id": self.drone_id}
+        return data, attributes
+
+    @classmethod
+    def from_pubsub_message(cls, data: bytes, attributes: Optional[Dict[str, str]] = None) -> "DroneTelemetryEvent":
+        body = json.loads(data.decode("utf-8"))
+        return cls(
+            drone_id=body["drone_id"],
+            latitude=body["latitude"],
+            longitude=body["longitude"],
+            heading=body["heading"],
+            battery_level=body["battery_level"],
+            reported_at=body["reported_at"],
+            sequence=body.get("sequence"),
+        )

crowddrop_sdk-0.1.0/crowddrop_sdk.egg-info/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: crowddrop-sdk
+Version: 0.1.0
+Summary: CrowdDrop's SDK for embodied-agent hardware. This release covers cloud_brain: the LLM stays in the cloud, the device is a thin actuator/sensor bridge over Pub/Sub.
+Project-URL: Repository, https://github.com/crowddrop-ai/crowddrop_ai_agents
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: cloud-brain
+Requires-Dist: crowddrop-pubsub-sdk<1.0.0,>=0.2.0; extra == "cloud-brain"
+Requires-Dist: requests<3.0.0,>=2.28.0; extra == "cloud-brain"
+Requires-Dist: google-auth<3.0.0,>=2.29.0; extra == "cloud-brain"
+
+# crowddrop-sdk
+
+CrowdDrop's SDK for connecting embodied-agent hardware to the CrowdDrop
+platform. It splits into two architecturally different scenarios:
+
+- **`cloud_brain`** (this release) - the LLM/tool-calling brain stays in
+  CrowdDrop's cloud backend; your device is a thin actuator/sensor bridge
+  over Google Cloud Pub/Sub. This is the right choice if your hardware can't
+  run an LLM locally but can run a real Python process.
+- **`edge_brain`** (planned, not yet released) - the LLM itself runs on your
+  device. A different SDK surface entirely, for hardware with real local
+  inference capacity.
+
+If you're building a companion-computer-class device (e.g. Raspberry-Pi
+class, full Linux + Python) that receives commands and reports telemetry,
+you want the `cloud-brain` extra:
+
+```bash
+pip install "crowddrop-sdk[cloud-brain]"
+```
+
+This pulls in `crowddrop-pubsub-sdk` (CrowdDrop's Pub/Sub transport library)
+as its only dependency - nothing else, so it stays light on constrained
+hardware. The base `crowddrop-sdk` install (no extra) has no dependencies at
+all.
+
+## Getting credentials
+
+There's no self-service signup. CrowdDrop issues one **agent device key**
+per physical device, tied to the persona it embodies, and hands it to you
+out-of-band along with the URL of the backend's token-vending endpoint. If
+you don't have both yet, ask whoever set up your CrowdDrop persona - there's
+no dashboard to generate one yourself. Your device never handles a raw GCP
+service-account key file: it trades its device key for a short-lived GCP
+access token by calling the token-vending endpoint (see
+`cloud_brain/drone/edge_agent.py`'s `fetch_gcp_access_token`), and refreshes
+that token automatically as it nears expiry.
+
+## API reference (`cloud_brain`)
+
+- **`crowddrop_sdk.cloud_brain.events.DRONE_COMMANDS`** - the eight
+  supported movement primitives, each a fixed pulse with no
+  duration/distance parameter: `take_off`, `land`, `forward`, `backward`,
+  `strafe_left`, `strafe_right`, `turn_left`, `turn_right`.
+- **`DroneCommandEvent(drone_id, command, issued_at, sequence)`** - what you
+  receive, one per command.
+- **`DroneTelemetryEvent(drone_id, latitude, longitude, heading,
+  battery_level, reported_at, sequence)`** - what you publish back.
+- **`crowddrop_sdk.cloud_brain.drone.channels.DroneCommandSubscriber`** -
+  pull-based subscriber for commands (you always initiate the connection
+  outward - nothing is ever pushed to your device).
+- **`crowddrop_sdk.cloud_brain.drone.channels.DroneTelemetryPublisher`** -
+  publisher for telemetry, with a `publish_telemetry(drone_id, latitude,
+  longitude, heading, battery_level)` convenience method.
+- **Two integration points you implement** - `handle_command(event)` (map
+  each command to your real flight-controller call) and
+  `read_battery_and_gps()` (return a real sensor reading). Both are stand-ins
+  in the example below; this SDK doesn't know your hardware's API.
+
+## Quickstart
+
+See [`cloud_brain/drone/README.md`](crowddrop_sdk/cloud_brain/drone/README.md)
+for a runnable example (`edge_agent.py`) and the exact env vars it needs.
+
+## Releasing (publishing a new version to PyPI)
+
+Releases are tag-triggered via `.github/workflows/publish-crowddrop-sdk.yml`,
+using PyPI's **Trusted Publishing** (OIDC) — no API token is stored as a
+GitHub secret.
+
+1. Bump `version` in `crowddrop_sdk/pyproject.toml`.
+2. Commit that change (on a branch, via the normal PR flow).
+3. Once merged, tag the merge commit and push the tag:
+   ```bash
+   git tag crowddrop-sdk-v<version>   # e.g. crowddrop-sdk-v0.1.1
+   git push origin crowddrop-sdk-v<version>
+   ```
+   The tag push is what fires the workflow — it builds `crowddrop_sdk/` and
+   uploads it to [pypi.org/project/crowddrop-sdk](https://pypi.org/project/crowddrop-sdk/).
+   No other trigger publishes this package.
+
+If `cloud-brain`'s dependency on `crowddrop-pubsub-sdk` (see `pyproject.toml`)
+needs bumping too, release `pubsub_sdk` first — see its own README's
+"Releasing" section, same mechanism, separate workflow/tag prefix
+(`pubsub-sdk-v*`).
+
+**One-time setup, not yet done as of this writing — needed before the first
+tag push, and again only if this ever moves to a different PyPI
+account/org:**
+- Register a **pending publisher** for `crowddrop-sdk` at
+  https://pypi.org/manage/account/publishing/ — this can be done before the
+  PyPI project exists, so it covers the *first-ever* release too, not just
+  subsequent ones. Fill in: PyPI project name `crowddrop-sdk`, repo owner
+  `crowddrop-ai`, repo name `crowddrop_ai_agents`, workflow filename
+  `publish-crowddrop-sdk.yml`, environment name `pypi`. Requires a PyPI
+  account with 2FA enabled — no API token to generate or store.
+- The `pypi` GitHub Environment referenced by the workflow is created
+  automatically the first time the workflow runs against it; create it
+  manually in this repo's Settings → Environments beforehand only if you
+  want a required-reviewer protection rule (so a tag push pauses for human
+  approval before it actually publishes).
+- `../scripts/publish_python_packages.sh` (manual `build` + `twine upload`)
+  is kept as a fallback/local-dry-run tool only — with a pending publisher
+  registered, it's no longer needed even for the first release.
+
+Versioning is manual — nothing cross-checks the tag against
+`pyproject.toml`'s `version`. Bump the file first, commit, *then* tag that
+exact commit; tagging a commit whose `pyproject.toml` still has an
+already-published version will fail the upload (PyPI rejects re-uploading an
+existing version).

crowddrop_sdk-0.1.0/crowddrop_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+crowddrop_sdk/__init__.py
+crowddrop_sdk.egg-info/PKG-INFO
+crowddrop_sdk.egg-info/SOURCES.txt
+crowddrop_sdk.egg-info/dependency_links.txt
+crowddrop_sdk.egg-info/requires.txt
+crowddrop_sdk.egg-info/top_level.txt
+crowddrop_sdk/cloud_brain/__init__.py
+crowddrop_sdk/cloud_brain/events.py
+crowddrop_sdk/cloud_brain/drone/__init__.py
+crowddrop_sdk/cloud_brain/drone/channels.py
+crowddrop_sdk/cloud_brain/drone/edge_agent.py

crowddrop_sdk-0.1.0/crowddrop_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

crowddrop_sdk-0.1.0/crowddrop_sdk.egg-info/requires.txt

@@ -0,0 +1,5 @@
+
+[cloud-brain]
+crowddrop-pubsub-sdk<1.0.0,>=0.2.0
+requests<3.0.0,>=2.28.0
+google-auth<3.0.0,>=2.29.0

crowddrop_sdk-0.1.0/crowddrop_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+crowddrop_sdk

crowddrop_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "crowddrop-sdk"
+version = "0.1.0"
+description = "CrowdDrop's SDK for embodied-agent hardware. This release covers cloud_brain: the LLM stays in the cloud, the device is a thin actuator/sensor bridge over Pub/Sub."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = []
+
+[project.optional-dependencies]
+cloud-brain = [
+  "crowddrop-pubsub-sdk>=0.2.0,<1.0.0",
+  "requests>=2.28.0,<3.0.0",
+  "google-auth>=2.29.0,<3.0.0",
+]
+
+[project.urls]
+Repository = "https://github.com/crowddrop-ai/crowddrop_ai_agents"
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

crowddrop_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+