Enhance documentation for Runtime blocking behavior and interactive usage #333
Conversation
…sage - Added a section in the Getting Started guide to highlight the blocking nature of `Runtime.start()`, particularly in interactive environments like Jupyter notebooks and Python REPLs. - Provided alternative approaches for running the runtime in the background using threading and asyncio, ensuring users can continue their interactive sessions without interruption. - Updated the index and create-runtime documentation to reference the new guidance on handling blocking operations. - Removed the satellites documentation as part of a cleanup effort, consolidating relevant information into the main guides.
NiveditJain
added
documentation
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. Caution Review failedThe pull request is closed. 📝 WalkthroughSummary by CodeRabbit
WalkthroughDocumentation updates: add Runtime setup prerequisites and env var guidance, clarify that Runtime.start() is blocking with non-blocking examples, expand Advanced runtime example, replace ASCII architecture with a Mermaid diagram, and enforce a string-only v1 data model with an example. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Developer as Developer
participant Node as Your Nodes
participant Runtime as Runtime
participant StateMgr as State Manager
Developer->>Runtime: Configure runtime (state_manager_uri, key, batch_size, workers, poll_interval)
Note over Runtime: start() is blocking
Developer->>Runtime: start() -- (run as thread / asyncio task / script)
Runtime->>StateMgr: Connect & poll for tasks
StateMgr-->>Runtime: Tasks / state updates
Runtime->>Node: Invoke handler with string Inputs/Secrets
Node-->>Runtime: Return string Outputs
Runtime->>StateMgr: Report results/state
alt Shutdown
Developer-->>Runtime: Stop
Runtime->>StateMgr: Disconnect
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Possibly related PRs
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: ASSERTIVE Plan: Pro 💡 Knowledge Base configuration:
You can enable these sources in your CodeRabbit configuration. 📒 Files selected for processing (1)
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary of Changes
Hello @NiveditJain, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!
This pull request significantly improves the user documentation by addressing the blocking behavior of Runtime.start(), offering practical solutions for interactive environments, and streamlining the setup instructions. The changes aim to enhance the user experience by preventing common pitfalls and providing clearer guidance on integrating the runtime effectively into various workflows.
Highlights
- Documentation Enhancement for Runtime Blocking Behavior: Added a new section in the Getting Started guide to clearly explain the blocking nature of
Runtime.start()and its implications, especially in interactive environments. - Alternative Approaches for Interactive Usage: Provided practical examples and guidance on how to run the runtime in the background using Python's
threadingmodule andasynciotasks, ensuring interactive sessions remain responsive. - Updated Runtime Setup Prerequisites: Integrated a new 'Prerequisites' section into the
create-runtimedocumentation, detailing the necessary steps for setting up the state manager and configuring environment variables before creating a runtime. - Improved Documentation Navigation and Clarity: Updated the main index and
create-runtimedocumentation to reference the new guidance on handling blocking operations, and replaced an ASCII architecture diagram with a more modern Mermaid diagram for better visual clarity.
Using Gemini Code Assist
The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.
Invoking Gemini
You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.
| Feature | Command | Description |
|---|---|---|
| Code Review | /gemini review |
Performs a code review for the current pull request in its current state. |
| Pull Request Summary | /gemini summary |
Provides a summary of the current pull request in its current state. |
| Comment | @gemini-code-assist | Responds in comments when explicitly tagged, both in issue comments and review comments. |
| Help | /gemini help |
Displays a list of available commands. |
Customization
To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.
Limitations & Feedback
Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.
You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.
Footnotes
-
Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩
There was a problem hiding this comment.
Code Review
This pull request significantly improves the documentation by clarifying the blocking behavior of Runtime.start() and providing clear, actionable alternatives for users in interactive environments. The changes are well-structured, using admonitions and tabbed content effectively to enhance readability. The addition of prerequisites in the create-runtime.md guide and the update from ASCII art to a Mermaid diagram are also welcome improvements. I have one suggestion to improve the clarity of an asyncio code example.
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (12)
docs/docs/exosphere/create-runtime.md(2 hunks)docs/docs/getting-started.md(2 hunks)docs/docs/index.md(1 hunks)docs/docs/satellites/exospherehost/call-webhook.md(0 hunks)docs/docs/satellites/exospherehost/deepseek-r1-distrill-llama-70b.md(0 hunks)docs/docs/satellites/exospherehost/forward-logs.md(0 hunks)docs/docs/satellites/exospherehost/get-files.md(0 hunks)docs/docs/satellites/exospherehost/move-file.md(0 hunks)docs/docs/satellites/exospherehost/parse-with-docling.md(0 hunks)docs/docs/satellites/exospherehost/send-alert.md(0 hunks)docs/docs/satellites/exospherehost/send-email.md(0 hunks)docs/docs/satellites/index.md(0 hunks)
💤 Files with no reviewable changes (9)
- docs/docs/satellites/exospherehost/move-file.md
- docs/docs/satellites/exospherehost/forward-logs.md
- docs/docs/satellites/exospherehost/get-files.md
- docs/docs/satellites/exospherehost/call-webhook.md
- docs/docs/satellites/exospherehost/send-alert.md
- docs/docs/satellites/exospherehost/deepseek-r1-distrill-llama-70b.md
- docs/docs/satellites/exospherehost/send-email.md
- docs/docs/satellites/index.md
- docs/docs/satellites/exospherehost/parse-with-docling.md
🧰 Additional context used
🪛 LanguageTool
docs/docs/exosphere/create-runtime.md
[grammar] ~7-~7: Use correct spacing
Context: ...nd configure your environment variables. ### Prerequisites 1. **Start the State Mana...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~9-~9: Use correct spacing
Context: ...nvironment variables. ### Prerequisites 1. Start the State Manager: Run the state...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~11-~11: Use correct spacing
Context: ... the state manager using Docker Compose: bash docker-compose up -d For detailed setup instructions, see [St...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~15-~15: Use correct spacing
Context: ...anager Setup](./state-manager-setup.md). 2. Set Environment Variables: Configure y...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~17-~17: Use correct spacing
Context: ...iables**: Configure your authentication: bash export EXOSPHERE_STATE_MANAGER_URI="your-state-manager-uri" export EXOSPHERE_API_KEY="your-api-key" Or create a .env file: ```bash E...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~23-~23: Use correct spacing
Context: ..." Or create a `.env` file: bash EXOSPHERE_STATE_MANAGER_URI=your-state-manager-uri EXOSPHERE_API_KEY=your-api-key ### Creating a Runtime === "Basic" p...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~29-~29: There might be a mistake here.
Context: ...r-api-key ### Creating a Runtime === "Basic" python hl_lines="17-...
(QB_NEW_EN)
[grammar] ~94-~94: Use correct spacing
Context: ... ``` !!! warning "Blocking Operation" Runtime.start() is a blocking operatio...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~95-~95: Use correct spacing
Context: ...sider running it in a background thread: python import threading def run_runtime(): runtime.start() thread = threading.Thread(target=run_runtime, daemon=True) thread.start() See the Getting Started guide for more alternatives. ## Runtime Parameters ### Required Paramet...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
docs/docs/index.md
[grammar] ~66-~66: Use correct spacing
Context: ...behavior) for non-blocking alternatives. ### Run it Run the server with: ```bash uv...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
docs/docs/getting-started.md
[grammar] ~89-~89: Use correct spacing
Context: ...t() ``` ## Important: Blocking Behavior Note: Runtime.start() is a blocking ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~91-~91: Use correct spacing
Context: ... like Jupyter notebooks or Python REPLs. ### For Interactive Environments If you're ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~93-~93: Use correct spacing
Context: ...REPLs. ### For Interactive Environments If you're working in a Jupyter notebook ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~95-~95: Use correct spacing
Context: ...ython REPL, consider these alternatives: === "Background Thread" ```python ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~97-~97: Use correct spacing
Context: ...e alternatives: === "Background Thread" python import threading # Create the runtime runtime = Runtime( namespace="MyProject", name="DataProcessor", nodes=[SampleNode] ) # Run in a background thread def run_runtime(): runtime.start() thread = threading.Thread(target=run_runtime, daemon=True) thread.start() # Your interactive session continues here print("Runtime is running in the background!") === "Asyncio Task" ```python im...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~120-~120: Use correct spacing
Context: ...ackground!") === "Asyncio Task" python import asyncio # Create the runtime runtime = Runtime( namespace="MyProject", name="DataProcessor", nodes=[SampleNode] ) # Run as an asyncio task (if you're in an async context) async def main(): task = runtime.start() # Returns a task when in an existing event loop # You can now do other async work while the runtime runs await asyncio.sleep(1) # Example: do other work return task # In Jupyter: await main() === "Production Script" python ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~142-~142: Use correct spacing
Context: ... main() === "Production Script" python # For production scripts, the blocking behavior is usually desired if name == "main": Runtime( namespace="MyProject", name="DataProcessor", nodes=[SampleNode] ).start() # Blocks and runs forever ``` ## Next Steps Now that you have the basics...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
🪛 markdownlint-cli2 (0.17.2)
docs/docs/exosphere/create-runtime.md
12-12: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
14-14: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
18-18: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
22-22: Trailing spaces
Expected: 0 or 2; Actual: 3
(MD009, no-trailing-spaces)
24-24: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
29-29: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
96-96: Trailing spaces
Expected: 0 or 2; Actual: 4
(MD009, no-trailing-spaces)
97-97: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🔇 Additional comments (4)
docs/docs/index.md (1)
65-66: Interactive environments note is helpful; verify anchor remains correct.Link targets “getting-started.md#important-blocking-behavior”. If the section title changes, this anchor will break. Keep it in sync.
docs/docs/getting-started.md (3)
89-92: Clear statement about blocking behavior.Accurate and actionable. Nice placement before alternatives.
145-152: Production-script guidance LGTM.Blocking in main is the expected pattern.
123-140: Asyncio example is correct:runtime.start()returns a Task in an existing loop
TheRuntime.start()implementation usesloop.create_task(self._start())when called inside an event loop, so the docs’ note that it “returns a task when in an existing event loop” is accurate.Likely an incorrect or invalid review comment.
| Before creating a runtime, you need to set up the state manager and configure your environment variables. | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| 1. **Start the State Manager**: Run the state manager using Docker Compose: | ||
| ```bash | ||
| docker-compose up -d | ||
| ``` | ||
| For detailed setup instructions, see [State Manager Setup](./state-manager-setup.md). | ||
|
|
||
| 2. **Set Environment Variables**: Configure your authentication: | ||
| ```bash | ||
| export EXOSPHERE_STATE_MANAGER_URI="your-state-manager-uri" | ||
| export EXOSPHERE_API_KEY="your-api-key" | ||
| ``` | ||
|
|
||
| Or create a `.env` file: | ||
| ```bash | ||
| EXOSPHERE_STATE_MANAGER_URI=your-state-manager-uri | ||
| EXOSPHERE_API_KEY=your-api-key | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Prereqs: prefer “docker compose” and fix markdownlint issues around fences.
- Use modern Compose syntax.
- Add blank lines around fenced blocks and after lists per MD031; remove trailing spaces.
- ```bash
- docker-compose up -d
- ```
- For detailed setup instructions, see [State Manager Setup](./state-manager-setup.md).
+
+ ```bash
+ docker compose up -d
+ ```
+
+ For detailed setup instructions, see [State Manager Setup](./state-manager-setup.md).
@@
- ```bash
- export EXOSPHERE_STATE_MANAGER_URI="your-state-manager-uri"
- export EXOSPHERE_API_KEY="your-api-key"
- ```
-
- Or create a `.env` file:
- ```bash
- EXOSPHERE_STATE_MANAGER_URI=your-state-manager-uri
- EXOSPHERE_API_KEY=your-api-key
- ```
+
+ ```bash
+ export EXOSPHERE_STATE_MANAGER_URI="your-state-manager-uri"
+ export EXOSPHERE_API_KEY="your-api-key"
+ ```
+
+ Or create a `.env` file:
+
+ ```bash
+ EXOSPHERE_STATE_MANAGER_URI=your-state-manager-uri
+ EXOSPHERE_API_KEY=your-api-key
+ ```🧰 Tools
🪛 LanguageTool
[grammar] ~7-~7: Use correct spacing
Context: ...nd configure your environment variables. ### Prerequisites 1. **Start the State Mana...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~9-~9: Use correct spacing
Context: ...nvironment variables. ### Prerequisites 1. Start the State Manager: Run the state...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~11-~11: Use correct spacing
Context: ... the state manager using Docker Compose: bash docker-compose up -d For detailed setup instructions, see [St...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~15-~15: Use correct spacing
Context: ...anager Setup](./state-manager-setup.md). 2. Set Environment Variables: Configure y...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~17-~17: Use correct spacing
Context: ...iables**: Configure your authentication: bash export EXOSPHERE_STATE_MANAGER_URI="your-state-manager-uri" export EXOSPHERE_API_KEY="your-api-key" Or create a .env file: ```bash E...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~23-~23: Use correct spacing
Context: ..." Or create a `.env` file: bash EXOSPHERE_STATE_MANAGER_URI=your-state-manager-uri EXOSPHERE_API_KEY=your-api-key ### Creating a Runtime === "Basic" p...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
🪛 markdownlint-cli2 (0.17.2)
12-12: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
14-14: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
18-18: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
22-22: Trailing spaces
Expected: 0 or 2; Actual: 3
(MD009, no-trailing-spaces)
24-24: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
In docs/docs/exosphere/create-runtime.md around lines 7 to 28, replace legacy
docker-compose usage with the modern "docker compose" command and fix
markdownlint MD031 issues by ensuring there is a blank line before and after
each fenced code block and after list items, remove any trailing spaces, and
keep the fenced code block language labels (e.g., ```bash) directly on the
opening fence; update the two blocks shown to use "docker compose up -d" and add
the required blank lines around the ```bash blocks and the ".env" section as
described.
🧹 Nitpick (assertive)
Code snippet variables vs env: avoid NameError in later examples.
Advanced example uses EXOSPHERE_STATE_MANAGER_URI/EXOSPHERE_API_KEY as Python names. Recommend showing os.getenv(...) or load_dotenv() usage explicitly before they are referenced.
Offer to patch if you confirm desired style (os.getenv vs dotenv).
🧰 Tools
🪛 LanguageTool
[grammar] ~7-~7: Use correct spacing
Context: ...nd configure your environment variables. ### Prerequisites 1. **Start the State Mana...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~9-~9: Use correct spacing
Context: ...nvironment variables. ### Prerequisites 1. Start the State Manager: Run the state...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~11-~11: Use correct spacing
Context: ... the state manager using Docker Compose: bash docker-compose up -d For detailed setup instructions, see [St...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~15-~15: Use correct spacing
Context: ...anager Setup](./state-manager-setup.md). 2. Set Environment Variables: Configure y...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~17-~17: Use correct spacing
Context: ...iables**: Configure your authentication: bash export EXOSPHERE_STATE_MANAGER_URI="your-state-manager-uri" export EXOSPHERE_API_KEY="your-api-key" Or create a .env file: ```bash E...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~23-~23: Use correct spacing
Context: ..." Or create a `.env` file: bash EXOSPHERE_STATE_MANAGER_URI=your-state-manager-uri EXOSPHERE_API_KEY=your-api-key ### Creating a Runtime === "Basic" p...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
🪛 markdownlint-cli2 (0.17.2)
12-12: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
14-14: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
18-18: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
22-22: Trailing spaces
Expected: 0 or 2; Actual: 3
(MD009, no-trailing-spaces)
24-24: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
In docs/docs/exosphere/create-runtime.md around lines 7 to 28, the tutorial
references EXOSPHERE_STATE_MANAGER_URI and EXOSPHERE_API_KEY as Python variables
later which can cause NameError; update the doc to explicitly show how to load
those values (either via os.getenv or via python-dotenv's load_dotenv) before
they are referenced, e.g. add a short Python snippet that imports os (and
dotenv.load_dotenv if using .env), calls load_dotenv() when appropriate, and
assigns state_manager_uri = os.getenv("EXOSPHERE_STATE_MANAGER_URI") and api_key
= os.getenv("EXOSPHERE_API_KEY") so later examples use those variables safely;
choose one style (os.getenv alone or dotenv + os.getenv) and keep examples
consistent, and confirm if you want me to patch the file with the chosen style.
| !!! warning "Blocking Operation" | ||
| `Runtime.start()` is a blocking operation that runs indefinitely. In interactive environments like Jupyter notebooks, consider running it in a background thread: | ||
|
|
||
| ```python | ||
| import threading | ||
|
|
||
| def run_runtime(): | ||
| runtime.start() | ||
|
|
||
| thread = threading.Thread(target=run_runtime, daemon=True) | ||
| thread.start() | ||
| ``` | ||
|
|
||
| See the [Getting Started guide](../getting-started.md#important-blocking-behavior) for more alternatives. | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Blocking warning: ensure fenced code block renders (not indented-code).
Markdownlint flagged MD046. Keep fenced code inside the admonition with 4-space indentation (MkDocs Material), but avoid extra leading spaces that turn it into an indented block.
- ```python
- import threading
-
- def run_runtime():
- runtime.start()
-
- thread = threading.Thread(target=run_runtime, daemon=True)
- thread.start()
- ```
+ ```python
+ import threading
+
+ def run_runtime():
+ runtime.start()
+
+ thread = threading.Thread(target=run_runtime, daemon=True)
+ thread.start()
+ ```Also, consider adding a line noting how to stop the runtime cleanly (mirroring Getting Started).
🧰 Tools
🪛 LanguageTool
[grammar] ~94-~94: Use correct spacing
Context: ... ``` !!! warning "Blocking Operation" Runtime.start() is a blocking operatio...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
[grammar] ~95-~95: Use correct spacing
Context: ...sider running it in a background thread: python import threading def run_runtime(): runtime.start() thread = threading.Thread(target=run_runtime, daemon=True) thread.start() See the Getting Started guide for more alternatives. ## Runtime Parameters ### Required Paramet...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
🪛 markdownlint-cli2 (0.17.2)
96-96: Trailing spaces
Expected: 0 or 2; Actual: 4
(MD009, no-trailing-spaces)
97-97: Code block style
Expected: fenced; Actual: indented
(MD046, code-block-style)
🤖 Prompt for AI Agents
In docs/docs/exosphere/create-runtime.md around lines 94 to 108, the fenced
Python code inside the admonition is accidentally treated as an indented code
block which triggers MD046; convert it to a proper fenced code block by ensuring
the triple backticks with the language marker are inside the admonition and not
prefixed by extra leading spaces (remove the stray indented opening/closing
backticks and place ```python before the code and ``` after), and while there,
add a brief one-line note after the code snippet explaining how to stop the
runtime cleanly (e.g., a short sentence referencing the Getting Started guide or
suggesting runtime.stop() / interrupt handling).
| ).start() | ||
| ``` | ||
|
|
||
| ## Important: Blocking Behavior |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Fix minor spacing/markdownlint nits around headings and fences.
Ensure a single blank line before/after headings and fenced code blocks; remove double spaces flagged by LanguageTool/MD031.
Also applies to: 91-91, 93-93, 95-95, 97-97, 120-120, 142-142
🧰 Tools
🪛 LanguageTool
[grammar] ~89-~89: Use correct spacing
Context: ...t() ``` ## Important: Blocking Behavior Note: Runtime.start() is a blocking ...
(QB_NEW_EN_OTHER_ERROR_IDS_5)
🤖 Prompt for AI Agents
In docs/docs/getting-started.md around lines 89 (and also 91, 93, 95, 97, 120,
142), headings and fenced code blocks violate markdownlint/MD031 and spacing
rules: ensure there is exactly one blank line before and after each heading and
each fenced code block, remove any trailing double spaces flagged by
LanguageTool, and normalize surrounding blank lines so there are no consecutive
blank lines; update those specific lines so headings have a single preceding and
following blank line and fenced blocks are separated by one blank line on both
sides.
| ```python | ||
| import threading | ||
|
|
||
| # Create the runtime | ||
| runtime = Runtime( | ||
| namespace="MyProject", | ||
| name="DataProcessor", | ||
| nodes=[SampleNode] | ||
| ) | ||
|
|
||
| # Run in a background thread | ||
| def run_runtime(): | ||
| runtime.start() | ||
|
|
||
| thread = threading.Thread(target=run_runtime, daemon=True) | ||
| thread.start() | ||
|
|
||
| # Your interactive session continues here | ||
| print("Runtime is running in the background!") | ||
| ``` |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Background-thread pattern: add a minimal shutdown note.
Daemon threads exit abruptly on interpreter shutdown. Recommend documenting how to stop the runtime (e.g., a stop() API or signal handling) to avoid partial work loss.
- thread = threading.Thread(target=run_runtime, daemon=True)
+ thread = threading.Thread(target=run_runtime, daemon=True)
thread.start()
- # Your interactive session continues here
+ # Your interactive session continues here. To stop cleanly, prefer a provided
+ # `runtime.stop()` or send KeyboardInterrupt in terminals if supported.
print("Runtime is running in the background!")📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ```python | |
| import threading | |
| # Create the runtime | |
| runtime = Runtime( | |
| namespace="MyProject", | |
| name="DataProcessor", | |
| nodes=[SampleNode] | |
| ) | |
| # Run in a background thread | |
| def run_runtime(): | |
| runtime.start() | |
| thread = threading.Thread(target=run_runtime, daemon=True) | |
| thread.start() | |
| # Your interactive session continues here | |
| print("Runtime is running in the background!") | |
| ``` | |
| thread = threading.Thread(target=run_runtime, daemon=True) | |
| thread.start() | |
| # Your interactive session continues here. To stop cleanly, prefer a provided | |
| # `runtime.stop()` or send KeyboardInterrupt in terminals if supported. | |
| print("Runtime is running in the background!") |
🤖 Prompt for AI Agents
In docs/docs/getting-started.md around lines 99 to 118, the background-thread
example uses a daemon thread but lacks guidance for graceful shutdown; add a
short note instructing users to stop the runtime explicitly to avoid abrupt
termination—describe calling runtime.stop() (or a provided shutdown API),
optionally sending a termination signal (SIGINT/SIGTERM) handled by the runtime,
and joining the thread (thread.join(timeout)) to wait for cleanup; include a
one- or two-sentence example pattern and a warning that daemon threads may
terminate mid-work if not shut down properly.
| name="HelloWorld", | ||
| nodes=[HelloWorldNode] | ||
| ).start() | ||
| ).start() # Note: This blocks the main thread |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Good callout on blocking behavior in the quickstart snippet.
Concise and discoverable. Consider the phrasing “Blocks the main thread” (sentence-case) for consistency with other comments in the docs set.
-).start() # Note: This blocks the main thread
+).start() # Blocks the main thread📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ).start() # Note: This blocks the main thread | |
| ).start() # Blocks the main thread |
🤖 Prompt for AI Agents
In docs/docs/index.md around line 62, update the quickstart snippet comment text
to match the docs' sentence-case style: replace "Note: This blocks the main
thread" with "Blocks the main thread" (remove "Note:" and capitalize only the
first word) so the phrasing is consistent with other comments across the
documentation.
1 participant
Runtime.start(), particularly in interactive environments like Jupyter notebooks and Python REPLs.