Skip to content

docs: document PRAISONAI_RUN_SYNC_TIMEOUT and shutdown() API (fixes #227) #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MervinPraison wants to merge 1 commit into
base: main
Choose a base branch
from
+50 −0
Open

docs: document PRAISONAI_RUN_SYNC_TIMEOUT and shutdown() API (fixes #227) #229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions docs/cli/env.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,19 @@ praisonai env show
praisonai env check
```

## Related Environment Variables

PraisonAI supports several environment variables for configuration and security:

| Variable | Purpose |
|----------|---------|
| `PRAISONAI_ALLOW_LOCAL_TOOLS` | Enable local tools.py file loading |
| `PRAISONAI_ALLOW_JOB_WORKFLOWS` | Enable job workflow execution |
| `PRAISONAI_BROWSER_ALLOW_REMOTE` | Enable remote browser access |
| `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for async operations (seconds) |
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Narrow the timeout description to the wrapper bridge.

Line 45 currently reads like this controls all async operations. The PR objective scopes it to the wrapper sync-to-async bridge, so the CLI table should avoid over-promising.

Suggested wording 
-| `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for async operations (seconds) |
+| `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for the wrapper sync-to-async bridge (seconds) |
📝 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.

Suggested change
| `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for async operations (seconds) |
| `PRAISONAI_RUN_SYNC_TIMEOUT` | Default timeout for the wrapper sync-to-async bridge (seconds) |
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/cli/env.mdx` at line 45, Update the table row for the environment
variable PRAISONAI_RUN_SYNC_TIMEOUT so its description specifies that the
timeout applies only to the wrapper sync-to-async bridge (not all async
operations); replace "Default timeout for async operations (seconds)" with a
concise phrasing such as "Default timeout for the wrapper sync-to-async bridge
(seconds)" so the CLI docs accurately reflect the PR scope.


For complete details and security implications, see [Security Environment Variables](/docs/features/security-environment-variables).

## See Also

- [Config](/docs/cli/config) - Configuration management
Expand Down
15 changes: 15 additions & 0 deletions docs/features/gateway.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -337,6 +337,21 @@ session_config = SessionConfig(

---

## Graceful Shutdown

Long-running servers can stop the wrapper's background async loop explicitly:

```python
from praisonai._async_bridge import shutdown

# On SIGTERM / server stop
shutdown()
```

`shutdown()` is also registered via `atexit`, so it runs automatically on interpreter exit. Call it manually when you need deterministic cleanup (flushing telemetry exporters, closing async HTTP/DB clients) before the process exits.
Comment on lines +345 to +351
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The shutdown function and its atexit registration are not present in the praisonai/_async_bridge.py file provided in this branch. This will lead to an ImportError when users try to follow the code example, and the described automatic cleanup will not occur. Please ensure the implementation is included in the codebase before documenting it as a public API.


---
Comment on lines +340 to +353
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Locate the async bridge module and inspect for shutdown() + atexit registration.
fd -t f '_async_bridge.py'
fd -t f '_async_bridge.py' --exec cat {}
echo "---- symbol search ----"
rg -nP '\b(def\s+shutdown|atexit\.register|__all__)\b' -C2

Repository: MervinPraison/PraisonAIDocs

Length of output: 50383

Remove the "Graceful Shutdown" section or correct the API reference.

The code snippet imports from praisonai._async_bridge import shutdown, but the praisonai/_async_bridge.py module contains only _ensure_background_loop() and run_sync() functions. There is no shutdown() function or atexit registration in that module. This import will raise ImportError at runtime. Either remove this section entirely or replace it with a corrected example if graceful shutdown support exists elsewhere in the API.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/features/gateway.mdx` around lines 340 - 353, The docs reference a
non-existent function import "shutdown" from praisonai._async_bridge; that
module only exposes _ensure_background_loop and run_sync and has no atexit
registration, so update the docs to either remove the entire "Graceful Shutdown"
section or replace the snippet with a correct API call that actually exists (do
not import shutdown from praisonai._async_bridge). If graceful shutdown
functionality exists under a different public symbol, change the import and
example to use that real function; otherwise delete the section to avoid
instructing users to import a missing symbol.


## CLI Commands

```bash
Expand Down
22 changes: 22 additions & 0 deletions docs/features/security-environment-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,8 @@ unset PRAISONAI_ALLOW_LOCAL_TOOLS
- Agent API calls
- Real-time UI interactions

As of recent PraisonAI versions, the `PRAISONAI_ALLOW_LOCAL_TOOLS` gate is enforced consistently across the CLI (`praisonai run`), YAML workflows, and Python (`AgentsGenerator`) entry points. Previously it was only enforced on one path.

**Usage Example**:
```python
from praisonaiagents import Agent
Expand Down Expand Up @@ -185,6 +187,22 @@ server = BrowserServer(host="0.0.0.0", port=8080)
server.start()
```

### PRAISONAI_RUN_SYNC_TIMEOUT

Default maximum seconds the wrapper's sync-to-async bridge will wait for a coroutine to complete.

**Default:** `300` (5 minutes)

```bash
# Tighten for latency-sensitive servers
export PRAISONAI_RUN_SYNC_TIMEOUT=30

# Loosen for long-running batch jobs
export PRAISONAI_RUN_SYNC_TIMEOUT=3600
```

Applies to every `praisonai` CLI entry and wrapper-based server (gateway, a2u, mcp_server, scheduler). The SDK (`praisonaiagents`) uses a separate bridge — see [Async Bridge](/docs/features/async-bridge).
Comment on lines +190 to +204
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The PRAISONAI_RUN_SYNC_TIMEOUT environment variable is not currently implemented in praisonai/_async_bridge.py. The run_sync function does not read this variable, and it defaults to None (infinite wait) rather than the 300 seconds mentioned. Additionally, the link [Async Bridge](/docs/features/async-bridge) appears to be broken as the target file is missing from the documentation structure. Please verify the implementation and the documentation links.

Comment on lines +190 to +204
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify PRAISONAI_RUN_SYNC_TIMEOUT is consumed by wrapper entry points
# and that the public shutdown() hook exists.

set -euo pipefail

echo "Checking timeout env var usage and run_sync call sites..."
rg -n -C3 'PRAISONAI_RUN_SYNC_TIMEOUT|run_sync\s*\(' --glob '!docs/**'

echo
echo "Checking shutdown API definition..."
rg -n -C3 'def\s+shutdown\s*\(' --glob '!docs/**'

Repository: MervinPraison/PraisonAIDocs

Length of output: 42789

🏁 Script executed:

# Check the _async_bridge.py implementation for timeout handling and shutdown
cat -n praisonai/_async_bridge.py | head -100

Repository: MervinPraison/PraisonAIDocs

Length of output: 2512

🏁 Script executed:

# Search for where PRAISONAI_RUN_SYNC_TIMEOUT might be read/set
rg -n "RUN_SYNC_TIMEOUT|getenv.*timeout|environ.*timeout" --glob '!docs/**'

Repository: MervinPraison/PraisonAIDocs

Length of output: 53

🏁 Script executed:

# Search for wrapper entry points (gateway, a2u, mcp_server, scheduler)
fd -e py -type f | xargs rg -l "gateway|a2u_server|mcp_server|scheduler" --glob '!docs/**' | head -5

Repository: MervinPraison/PraisonAIDocs

Length of output: 440

🏁 Script executed:

# Check if any wrapper code tries to read PRAISONAI_RUN_SYNC_TIMEOUT or pass timeout to run_sync
rg -n "run_sync\(" praisonai/endpoints/ praisonai/integrations/ --glob '!docs/**' -A2 -B2 | head -80

Repository: MervinPraison/PraisonAIDocs

Length of output: 3272

🏁 Script executed:

# Confirm there is no shutdown in _async_bridge
wc -l praisonai/_async_bridge.py
tail -20 praisonai/_async_bridge.py

Repository: MervinPraison/PraisonAIDocs

Length of output: 690

Document PRAISONAI_RUN_SYNC_TIMEOUT environment variable contract accurately or remove unsupported claims.

The documented environment variable is not consumed by the codebase:

  • No wrapper (base.py, a2u_server.py, managed_local.py) reads PRAISONAI_RUN_SYNC_TIMEOUT
  • run_sync() calls in wrappers pass no timeout parameter (except one hardcoded timeout=120)
  • The shutdown() hook does not exist in praisonai._async_bridge module

Either implement support for the environment variable (parse it in wrappers, pass it to run_sync() calls, and set the 300-second default) or update the documentation to reflect the actual behavior: timeouts are passed as explicit parameters only and no shutdown hook exists in _async_bridge.

Suggested documentation revision 
 ### PRAISONAI_RUN_SYNC_TIMEOUT
 
 Default maximum seconds the wrapper's sync-to-async bridge will wait for a coroutine to complete.
 
+**Type:** float seconds
 **Default:** `300` (5 minutes)
+**Recommended range:** use `30`-`300` for interactive servers; use larger values only for known long-running batch workloads.
 
 ```bash
 # Tighten for latency-sensitive servers
 export PRAISONAI_RUN_SYNC_TIMEOUT=30
 
 # Loosen for long-running batch jobs
 export PRAISONAI_RUN_SYNC_TIMEOUT=3600
+
+# Restore the default behavior
+unset PRAISONAI_RUN_SYNC_TIMEOUT

-Applies to every praisonai CLI entry and wrapper-based server (gateway, a2u, mcp_server, scheduler). The SDK (praisonaiagents) uses a separate bridge — see Async Bridge.
+Applies to praisonai CLI entries and wrapper-based servers (gateway, a2u, mcp_server, scheduler). The SDK (praisonaiagents) uses a separate bridge — see Async Bridge.


Alternatively, if this variable is not yet implemented, consider marking the section as "Planned" or deferring documentation until the feature is complete.
</details>

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against the current code and only fix it if needed.

In @docs/features/security-environment-variables.mdx around lines 190 - 204, The
docs claim PRAISONAI_RUN_SYNC_TIMEOUT is honored but the code never reads it;
implement support by parsing the PRAISONAI_RUN_SYNC_TIMEOUT env var (default
300) in the wrapper startup paths (e.g., code in base.py, a2u_server.py,
managed_local.py), pass that timeout value into calls to run_sync() instead of
hardcoding values (update any run_sync(...) calls to accept a timeout param) and
remove or stop referencing the non‑existent praisonai._async_bridge.shutdown
hook (or implement a proper shutdown in praisonai._async_bridge and call it if
you prefer); alternatively, if you choose not to implement it, update the docs
to remove the unsupported claims and mark the section as planned—refer to
PRAISONAI_RUN_SYNC_TIMEOUT, run_sync, and praisonai._async_bridge in your
changes.


</details>

<!-- fingerprinting:phantom:poseidon:ibis -->

<!-- This is an auto-generated comment by CodeRabbit -->


---

## Common Patterns
Expand All @@ -196,6 +214,7 @@ server.start()
export PRAISONAI_ALLOW_LOCAL_TOOLS=true
export PRAISONAI_ALLOW_JOB_WORKFLOWS=true
export PRAISONAI_BROWSER_ALLOW_REMOTE=true
export PRAISONAI_RUN_SYNC_TIMEOUT=30

# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export PRAISONAI_ALLOW_LOCAL_TOOLS=true' >> ~/.bashrc
Expand All @@ -208,13 +227,15 @@ echo 'export PRAISONAI_ALLOW_LOCAL_TOOLS=true' >> ~/.bashrc
unset PRAISONAI_ALLOW_LOCAL_TOOLS
unset PRAISONAI_ALLOW_JOB_WORKFLOWS
unset PRAISONAI_BROWSER_ALLOW_REMOTE
export PRAISONAI_RUN_SYNC_TIMEOUT=300

# Or use systemd service with secure environment
# /etc/systemd/system/praisonai.service
[Service]
Environment="PRAISONAI_ALLOW_LOCAL_TOOLS=false"
Environment="PRAISONAI_ALLOW_JOB_WORKFLOWS=false"
Environment="PRAISONAI_BROWSER_ALLOW_REMOTE=false"
Environment="PRAISONAI_RUN_SYNC_TIMEOUT=300"
```
</Tab>

Expand Down Expand Up @@ -258,6 +279,7 @@ Check if you use any of these features:
export PRAISONAI_ALLOW_LOCAL_TOOLS=true # If you use tools.py
export PRAISONAI_ALLOW_JOB_WORKFLOWS=true # If you use job workflows
export PRAISONAI_BROWSER_ALLOW_REMOTE=true # If you bind browser to 0.0.0.0
export PRAISONAI_RUN_SYNC_TIMEOUT=300 # Adjust timeout as needed
```
</Step>

Expand Down