DOCSEARCHbyAlgolia
Submit Docs

dora-rs/dora

repository·main·Indexed 26 days ago

https://github.com/dora-rs/dora

An agentic, dataflow-oriented robotic architecture built in Rust for real-time robotics and AI applications. It features high-performance IPC, multi-language support (C++, Python), and distributed deployment capabilities. The architecture utilizes a process-based runtime via the dora-coordinator, where operators run as independent processes communicating through a zenoh-based layer. It includes an experimental ROS2 Bridge for C++ nodes and supports Apache Arrow for typed data inputs.

Tokens
228K
Snippets
610
Records
1.1K
Agent score
81%

What's inside dora

  1. Overview of the Dora WebSocket Control Plane

    main

    Dora uses a single Axum-based WebSocket server to facilitate all communication between the CLI, coordinator, and daemons. This replaces a multi-port TCP design with a unified interface using JSON text frames for control messages and binary frames for topic data.

    Key Routing Information

    • /api/control (CLI): Used by the CLI to send commands and receive replies.
    • /api/daemon (Daemons): Used by daemons for registration, event reporting, and receiving commands.
    • /health (HTTP GET): Health check endpoint.

    Protocol Constraints

    • Wire Format: JSON text frames (control) and binary frames (topic data).
    • Protocol Pattern: UUID-correlated request-reply for commands, and fire-and-forget for events (like log streaming).
    • Message Size Limit: 1 MiB (MAX_CONTROL_MESSAGE_BYTES).
    • Concurrency Limit: 256 connections (MAX_WS_CONNECTIONS).

  2. Overview of Dora Architecture

    main

    Dora is an Agentic Dataflow-Oriented Robotic Architecture, a 100% Rust framework designed for building real-time robotics and AI applications. It uses a declarative YAML-based approach to define dataflows as directed graphs where nodes are connected via typed inputs and outputs.

    Key architectural features include:

    • Zero-copy IPC: Uses shared memory for messages >4KB and Apache Arrow for end-to-end columnar memory format.
    • Distributed by default: Uses Zenoh for shared memory between local nodes and automatic network fallback for cross-machine communication.
    • Multi-language support: Nodes can be written in Rust, Python, C, or C++ using native APIs.
    • Fault tolerance: Supports per-node restart policies (never, on-failure, always), exponential backoff, and circuit breakers.

  3. Dynamic Tool Addition and Fan-in Pattern

    main

    The Dynamic Agent Tools example demonstrates a specific architectural pattern for AI agents using dora:

    1. Fan-out to multiple tools: The agent sends requests to a single shared topic (e.g., tool-request). Multiple tool nodes can subscribe to this same topic.
    2. Tool-specific filtering: Each tool node is responsible for inspecting the incoming JSON payload and filtering for its own identifier (e.g., checking if the "tool" field matches its name).
    3. Fan-in (Multiple sources to one target): Multiple tools can send their responses back to the agent via a single input topic (e.g., agent/tool-response). Dora handles the interleaving of messages from these multiple sources based on arrival order.
    4. Runtime Extensibility: Using dora node add and dora node connect, new specialized nodes (like web search or database queries) can be integrated into the agent's capability set while the dataflow is running.

  4. Understand the Dora Hub Node Packaging and Distribution System

    main

    Dora Hub is the system for packaging, discovering, and distributing nodes in dora. It allows node authors to publish typed, versioned nodes and dataflow authors to use them via a single line in a YAML configuration.

    Key Concepts

    • Publishing: Node authors publish nodes by creating an index entry that pins their source to a specific git commit. No manual uploading of source code is required as the source remains in its original git repository.
    • Discovery: Users can search for nodes (e.g., dora hub search camera) using an offline-capable mechanism that does not require a hosted service.
    • Usage: In a dataflow.yml, nodes can be referenced using the hub: name@version syntax (e.g., hub: dora-yolo@^0.5). This automatically handles fetching, building, and running the node.
    • Validation: Input and output contracts are declared in a node manifest and are validated during dataflow composition using dora validate or dora build to catch wiring mistakes before runtime.
    • Reproducibility: The system uses lockfiles to pin source commits (or SHA256 hashes for binary forms), ensuring that --locked builds are reproducible.
    • Architecture: The hub: syntax desugars to dora's existing git: source machinery, supplemented by typed manifests and commit pinning in a catalog (dora-hub/node-index).

  5. Understand Dora performance characteristics

    main

    Dora's performance is optimized through several architectural choices:

    • Zero-copy IPC: For payloads >4KB, Dora uses Zenoh shared memory (SHM) to avoid copies. For payloads <4KB, it uses TCP with bincode.
    • Data Format: Uses Apache Arrow (zero-serde) for efficient data handling.
    • Threading: Uses lock-free channels (flume) and Rust async (tokio).
    • Fan-out: Uses Arc-wrapped data, providing $O(1)$ complexity per receiver.

    Tuning Tips:

    • Payload Size: Structure data to exceed 4KB to trigger shared memory benefits.
    • Operator Choice: Use Rust operators for compute-heavy tasks to avoid the Python GIL. Use Python operators for glue logic.
    • Deployment: Use local (single-machine) deployment for sub-millisecond latency. Cross-machine communication uses Zenoh pub-sub and is subject to network quality.

  6. Python API Reference Overview

    main

    The dora Python API provides interfaces for several core components:

    • Node API: For building dora nodes using the Node class.
    • Operator API: For building user-defined operators.
    • DataflowBuilder: For programmatically constructing dataflows using DataflowBuilder, Node (builder), Output (builder), and Operator (builder) classes.
    • CUDA Module: Specialized support for CUDA-accelerated tasks.

  7. Understand the Agentic QA Strategy for dora

    main

    The Agentic QA Strategy is a framework designed to verify code quality and correctness when code is authored by AI agents at high velocity. It addresses specific failures common in AI-generated code, such as tautological tests (tests that mirror implementation rather than specification), defensive code that is never exercised, and subtle system-level invariant violations.

    The strategy moves away from traditional code review toward measurable verification signals, including:

    • Mutation testing: Measuring if tests can actually detect bugs.
    • Property-based and fuzz testing: Generating unexpected inputs.
    • Architectural fitness tests: Encoding design decisions as executable tests to prevent architectural drift.
    • Dogfooding: Running real workloads to exercise system-level invariants.

    Verification is organized into three tiers based on latency:

    1. Tier 1 (PR gate): Runs on every PR, must be <15 min. Provides fast feedback to agents.
    2. Tier 2 (Nightly): Runs once per night, <4 hours. Catches slow-to-detect bugs.
    3. Tier 3 (Pre-release): Runs per minor version. Establishes the evidence base for a release.

  8. Understand Dora Communication Protocols

    main

    Dora uses different communication protocols depending on the component relationship:

    • CLI to Coordinator: Uses WebSocket over TCP (default port 6013). Control messages use a JSON-RPC-like format (Request/Response/Event), while topic data uses binary frames: [16-byte UUID][bincode payload].
    • Coordinator to Daemon: Uses WebSocket (route /api/daemon). The daemon connects to the coordinator and uses exponential backoff for retries.
    • Daemon to Node (Local): Uses TCP (default) or Shared Memory (for zero-copy). TCP uses [8-byte u64 LE length][bincode payload]. Shared memory is automatically used for messages $\ge$ 4096 bytes (ZERO_COPY_THRESHOLD).
    • Daemon to Daemon: Uses Zenoh pub-sub (Router port 7447, Peer port 5456) for inter-daemon communication across networks.

  9. Understand the Dora Hub Node Packaging & Distribution Spec

    main
    Dora Hub is a specification for packaging and distributing nodes within the Dora ecosystem. It introduces a manifest system (dora-node.yml) and a centralized index to allow users to discover, install, and run nodes using a hub: source descriptor. This system desugars to git-based sources with specific commit pins, ensuring reproducibility while providing a high-level discovery mechanism.

  10. Understand the Dora verification ladder

    main

    Dora employs multiple tiers of verification to ensure correctness, ranging from sampled testing to exhaustive model checking:

    TierToolPurposeExecution Frequency
    Example-based testscargo testVerifies sampled casesEvery commit (qa-fast/CI)
    Property-based testsproptestVerifies hundreds of random cases per propertyEvery commit (part of cargo test)
    UB detectionmiriDetects undefined behavior on executed pathsNightly (qa-nightly)
    Test-quality auditcargo-mutantsChecks if tests catch injected logic mutationsqa-deep (diff-scoped)
    Model checkingKani (CBMC)Proves properties hold for every input in the harness state spaceOn demand (make qa-kani) and nightly CI

  11. Benchmark Implementation Patterns

    main

    The benchmark demonstrates several key dora patterns for high-performance data processing:

    • Low-overhead binary transmission: Use send_output_raw() in nodes to achieve zero-overhead binary transmission.
    • Arrival timing: Use metadata.timestamp() in sinks to record precise arrival timestamps for latency analysis.
    • Burst buffering: Configure queue_size in the dataflow YAML (e.g., queue_size: 1000) to handle throughput bursts.
    • Zero-copy transport: Note that dora typically switches to shared memory transport at a 4KB threshold, which helps maintain flat latency even as payload sizes increase from 4KB to 4MB.

  12. Understand Zenoh Shared Memory Performance Trade-offs

    main

    Dora's implementation of Zenoh Shared Memory (SHM) offers significant performance improvements for large payloads but has specific characteristics to keep in mind:

    • Large Payloads (>= 4KB): Provides ~35% lower latency and 3-10x better throughput compared to the custom implementation by bypassing the daemon hop.
    • Small Payloads (< 2KB): Can be 55-80% slower due to Zenoh per-message overhead. Dora mitigates this by using a threshold to keep small messages on the TCP path.
    • First Message Latency: Expect a ~16x latency spike on the very first message due to Zenoh session initialization. This can be mitigated by pre-warming the session during node startup.
    • Data Path: Unlike the custom implementation, Zenoh SHM allows direct node-to-node communication, removing the daemon from the data path for local transfers.