Improving- Getting Started on dora-rs.ai (Part 1 of 4):Python Conversation #28

[Shiv-aurora]

@haixuanTao I accidentally deleted the previous PR while syncing my fork, but I have restored it and fixed the issue. Let me know if any further changes are needed.

Changes:

• Standardized terminology
• Improved step-by-step explanations and structure
• Addressed common issues users faced in setup

This is Part 1 of 4 in fully resolving dora-rs/dora#885. Suggestions and feedback are highly appreciated to ensure consistency before proceeding with the remaining parts!

[grkw]

Hi @Shiv-aurora , I was going through the Getting Started tutorial and it was not very clear, so I started writing a PR to fix it but I saw that you've already started that! I like what you have so far.

A few questions/comments:

In "1. Setting Up the Environment"

When I run the setup commands you have listed in your PR,

uv venv --seed -p 3.11
dora venv activate  # macOS/Linux

this is what I get:

Using CPython 3.11.8 interpreter at: /Users/gracekwak/miniconda3/bin/python3.11
Creating virtual environment with seed packages at: .venv
 + pip==25.0.1
 + setuptools==78.1.0
 + wheel==0.45.1
Activate with: source .venv/bin/activate
error: unrecognized subcommand 'venv'

Usage: dora <COMMAND>

For more information, try '--help'.

But I don't get that venv error when I run what's currently on the tutorial:

uv venv --seed -p 3.11
source .venv/bin/activate  # macOS/Linux

Maybe keep what's currently on the tutorial?

In "2. Creating a New Conversation"

You have dora new --kind conversation --lang python my_conversation but that gives an error. I think you mean dora new my_conversation --lang python to create a new project called my_conversation?

In creating a new project, it looks like by default, there are 3 nodes that are created: talker 1, talker 2, and listener 1. These nodes do start with the boilerplate talking/listening functionality (see the next section).

Maybe you could tell people to look at these nodes and then create a new node talker 3 which they build off of using the default node creation.

In "3. Adding Nodes to the Conversation" and "4. Understanding Node Functionality"

You seem to imply that talker and listener are particular classes of nodes that start out with some particular functionalities. You say "The talker node emits messages on an output stream" and "The listener node listens for incoming messages and processes them accordingly" -- but (I think) in reality, they're just the names of the (default) nodes that we create, and they both have this autogenerated code (that doesn't do anything besides print when it receives data from a node):

from dora import Node
import pyarrow as pa


def main():
    node = Node()

    for event in node:
        if event["type"] == "INPUT":
            if event["id"] == "TICK":
                print(
                    f"""Node received:
                id: {event["id"]},
                value: {event["value"]},
                metadata: {event["metadata"]}"""
                )

            elif event["id"] == "my_input_id":
                # Warning: Make sure to add my_output_id and my_input_id within the dataflow.
                node.send_output(
                    output_id="my_output_id", data=pa.array([1, 2, 3]), metadata={}
                )


if __name__ == "__main__":
    main()

I think that the person taking the tutorial has to add the line node.send_output(output_id="speech", data=pa.array(["Hello World"])) to the talker's main.py. And similarly, they have to add the line print(f"Listener received: {event['value'][0].as_py()}") to the listener's main.py.

In "6. Building and Running the Conversation"

It says "You should see output in the terminal similar to:" but I get a whole bunch of log printouts, see here (I did a slightly different example with talker/listener, but same idea): https://app.warp.dev/block/4g1upQKgPQfz5J7CzYHsPi

Maybe it would also be nice to say "after running for a bit, you can stop the run using Ctrl/Cmd+C. You'll see a folder called out which contains a subfolder for each run that you do (named with a long hash/UUID like 0195f399-3818-7d23-bc3b-735350c0f699). Each subfolder contains a log_NODENAME.txt file that logs relevant stuff from the run."

---

I want to note that I am new to Dora so I might not be correct in my assumptions, but I thought I'd share my thoughts, at the very least I can be like a beta-tester for your updated Getting Started guide. Lmk what you think! Maybe @haixuanTao has thoughts too?

[haixuanTao]

doesn't the formatting looks weird as there is spaces everywhere?

[Shiv-aurora]

I agree, I believe previously I added that to make it look less cluttered, Should i go ahead and remove those? and is there anything else that needs to be improvement?

[grkw]

Bumping my comment. Perhaps I'm just missing something but even if so, others who want to get started might also benefit from clarification.