Skip to main content

dynos-client

The HTTP client and command-line tool for talking to a DYNOS planning backend. You install this on your laptop or server, point it at a backend, and drive the planner from Python or the shell. The backend does the planning; this package gives you the network interface.

You usually combine it with a domain package (e.g. dynos-sentry-domain) that gives you the actual nouns and verbs your goals reference. dynos-client ships only the infrastructure: HTTP, CLI, mission builder, session-gateway authentication.

dynos-client depends on dynos-core, as do the domain files. The domain files also depend on this package. Specific robot missions or extensions, such as the adaptive sampling demo, depend on robot implementations.

Most users start here. pip install dynos-client plus a domain package and you can talk to a hosted backend immediately. You do not need to install the backend itself.

Install

pip install dynos-client

Pulls in dynos-core, requests, typer, and bcrypt. Registers a dynos console script.

Sessions and the backend

DYNOS backends run in two modes. Direct mode is a single process with no auth. This is fine for local development against a mock, or on-vehicle work. Session-gateway mode is multi-tenant, and most likely how you're be developing: a TLS endpoint accepts password logins, issues bearer tokens, and routes each user's traffic to a private subprocess (their session) with its own world model. The hosted backend at https://api.dynosplan.com is in this mode.

You authenticate once:

dynos login
# optionally, you can set the source. The default is the webpage, but this might be an on-ship server:
# dynos login --to https://api.dynosplan.com

That writes ~/.dynos/config.json (mode 0o600). Every subsequent dynos call, dynos session, and dynos connect reads the cached URL, token, and default session, so the --to flag is rarely needed after the first login.

A session is a private process that holds your world model. Create one before issuing goals:

dynos session create
dynos call health         # confirms the gateway is reachable
dynos session info        # confirms a session is selected

dynos session swap <name> switches the default; dynos session stop ends the current session. The CLI never silently picks a session for you. If your default session has expired or been stopped, commands error out with a hint to run swap or create.

CLI map

Command Purpose
dynos login / logout / whoami Authenticate against a session gateway and inspect the cache.
dynos call <subcmd> Talk to a running backend: health, goal, plan, execute, state, objects, trigger, reset, geojson, ...
dynos session <subcmd> Manage gateway sessions: create, list, info, swap, extend, reset, stop.
dynos connect <module>:<Class> Run as a servant; the backend dispatches actions over HTTP and your local code executes them.
dynos hash-password Produce a bcrypt hash for the gateway's admin user table. You can send this to the server admin (me) to change your pw

Run any of them with --help for full options.

60-second example

from dynos_client import RemoteOrchestrator

orch = RemoteOrchestrator.from_config()    # reads ~/.dynos/config.json
print(orch.health())

The shell equivalent:

dynos call health

Both go to the same endpoint. The Python form is the one you reach for when missions get longer than the CLI's 30-second HTTP timeout (see "Long-running plans" below).

Goal vs. trigger

There are two ways to make the backend do something, and they are not interchangeable.

dynos call execute (preferred). You set a goal, which is a desired symbolic state. The planner derives the prerequisite sequence. If something fails, the planner replans from the current state. This is what the system is designed for.

dynos call goal "full_coverage_of(site_alpha)"
dynos call plan        # optional: print the action sequence the planner picked
dynos call execute

dynos call trigger (debug only). Fires one transition directly, with no planner involvement and no precondition check. Convenient for confirming a custom @Action is wired up; not safe for anything that moves the vehicle. A careless trigger can leave the symbolic world in a state the planner doesn't trust (e.g. recording at(wp_end) without descent ever happening).

dynos call trigger "resample_zone(source_zone=site_alpha)"   # OK for debug

If you find yourself wanting to chain trigger calls, you actually want a goal. Let the planner sequence them.

Missions

A Mission chains plan blocks and action blocks. Each block runs to completion before the next starts; the planner replans at every block boundary using the state after the previous block.

from dynos_client import RemoteOrchestrator, Mission
from dynos_sentry.sentry import Zone, full_coverage_of

orch = RemoteOrchestrator.from_config(timeout_s=3600)

area_north = Zone("area_north", coordinate_frame="geographic",
    vertices=[[-70.67, 41.525], [-70.66, 41.525], [-70.66, 41.53], [-70.67, 41.53]],
    altitude=70.0, speed=0.8, coverage_width=170.0, robot_width=0.5)
area_south = Zone("area_south", coordinate_frame="geographic",
    vertices=[[-70.67, 41.52], [-70.66, 41.52], [-70.66, 41.525], [-70.67, 41.525]],
    altitude=70.0, speed=0.8, coverage_width=170.0, robot_width=0.5)
orch.create_object(area_north)
orch.create_object(area_south)

mission = Mission(name="two_surveys")
mission.add_plan([full_coverage_of(area_north)])
mission.add_plan([full_coverage_of(area_south)])
results = orch.execute_blocks(mission)

Mix action blocks (run a single transition immediately, no planning) with plan blocks (set a goal, planner derives the sequence):

from dynos_sentry.sentry import full_coverage_of

mission = Mission(name="custom_sequence")
mission.add_plan([full_coverage_of(area_north)])    # planned
mission.add_plan([full_coverage_of(area_south)])
results = orch.execute_blocks(mission)

A single plan block can carry multiple goals; the planner finds one plan that achieves all of them. Note what is not here: no takeover, descent, or abort steps. Those bookends (and the vehicle's abort/recovery) are added by the mission framework and the on-vehicle safety system, not by you -- a client never assembles lifecycle or abort steps, and never puts a phase in a goal. A plan block is the normal building block; an action block (a single transition, no planning) strips out the replanning context and is reserved for genuine imperative primitives.

Objects, dedup, and handles

create_object returns the backend record by default. When you submit a point whose coordinates match an existing one, the backend collapses them onto a single object and reports the canonical name under merged_into -- so the name you get back may differ from the one you sent, and you may no longer be holding the object that another call created earlier.

Pass return_ref=True to get a client-side handle bound to that canonical name, whether the object was freshly created or merged. Feed it straight into fluents and set_goal -- no need to read merged_into, and no string references:

from dynos_sentry.sentry import Coordinate, at

target = orch.create_object(
    Coordinate(latitude=45.95, longitude=-130.0, depth=100.0),
    return_ref=True,
)
orch.set_goal([at(target)])   # canonical whether created or merged

The raw record (created, merged_into, warning, ...) is still available on the handle as target._create_result if you need it.

Servants and dynos connect

When the action's implementation lives on your machine; your ML model, a sensor handler, a custom controller; you run a servant. The backend keeps planning; your code executes the assignments it dispatches. See dynos-adaptive-resampling's README for a full worked example.

dynos connect my_package.runnable:MyNode

A Runnable is a small class with three static methods (register, get_start_state, get_start_goal); the servant loop polls the backend for assignments and posts results back. dynos connect reads the same cached login as dynos call.

Custom actions in a client-only env

@Action and @Script (the decorators that bind a Python method to a Transition) are available directly from dynos_client.action, so an extension package imports them with no backend installed:

from dynos_client.action import Action, Script

In a client-only environment the decorator records the binding; the action fires when the class is registered against a backend that dispatches it (this is exactly how dynos-adaptive-resampling defines its resample_zone action).

Long-running plans

dynos call execute is synchronous: the backend holds the HTTP response open until every step in the plan has finished. The CLI defaults to a 30-second client-side timeout, so for any plan that takes longer your terminal will print Read timed out even though the backend is still happily executing. This times out the client, not the plan.

Two workarounds:

  1. Use Python with a longer timeout. RemoteOrchestrator.from_config(timeout_s=3600).
  2. Don't watch, open a second terminal and poll. dynos call state, dynos call goal, dynos call live-trace, dynos call live-log --wall.

Configuration

~/.dynos/config.json (mode 0o600) stores:

Key Source
backend_url dynos login --to ...
token dynos login (gateway-issued bearer)
username dynos login
role dynos login (user, admin)
default_session dynos session create / swap

Set DYNOS_CONFIG_PATH=/some/other/file.json to override the location (handy for tests; the public CLI honours the env var).

Public API

Symbol Purpose
RemoteOrchestrator The HTTP client; mirrors the backend's Orchestrator Python API.
RemoteAuthExpired Raised when the cached token is rejected; catch and reauthenticate.
Mission Builder for compound goal sequences.
PlanBlock Plan-derived block within a Mission (one or more goals -> planner).
ActionBlock / AnyActionBlock Single-action block within a Mission (no planning).

Next

Install dynos-sentry-domain to get Zone, Coordinate, full_coverage_of, and the rest of the goal vocabulary. The walkthrough at user_guide.md ties everything together end-to-end. A simple toy domain (warehouse) is also available.

Metadata

Release files for dynos-client 0.2.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dynos-client 0.2.5
File Size Uploaded Provenance Actions
dynos_client-0.2.5.tar.gz 56.3 kB Without provenance Details for dynos_client-0.2.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dynos-client 0.2.5
File Interpreter ABI Platform Actions
dynos_client-0.2.5-py3-none-any.whl Python 3 none any Details for dynos_client-0.2.5-py3-none-any.whl

Total release size: 116.5 kB

Release files / dynos_client-0.2.5.tar.gz

Download URL dynos_client-0.2.5.tar.gz
Size 56.3 kB
Tags Source
SHA-256 checksum
How to use checksums
b55f47a7d8fdb7a41782108efdd03674e23720428c6147a0f52d76ef14c0b078
BLAKE2b-256 checksum
How to use checksums
b127b88cc95c9500fa272fb612d9b4241873981d4f05ed5ba05ad12764f073d3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.10

Release files / dynos_client-0.2.5-py3-none-any.whl

Download URL dynos_client-0.2.5-py3-none-any.whl
Size 60.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5772020ed94eccc9cf77970170b4f70ec9159a91c056fa0a840e9bcc4384895c
BLAKE2b-256 checksum
How to use checksums
c46d2e6ec1f869c734bcf7e097b878b0bed69e6f986640c652f215b788cca175
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.10

Security for dynos-client 0.2.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page