PraisonAI 4.7.5__tar.gz → 4.7.7__tar.gz

{praisonai-4.7.5 → praisonai-4.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.7.5
+Version: 4.7.7
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,14 +11,14 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.7.3
-Requires-Dist: praisonai-code>=0.1.2
-Requires-Dist: praisonai-bot>=0.1.2
-Requires-Dist: praisonai-train>=0.1.2
-Requires-Dist: praisonai-browser>=0.1.2
-Requires-Dist: praisonai-mcp>=0.1.4
-Requires-Dist: praisonai-sandbox>=0.1.2
-Requires-Dist: praisonai-deploy>=0.1.2
+Requires-Dist: praisonaiagents>=1.7.5
+Requires-Dist: praisonai-code>=0.1.4
+Requires-Dist: praisonai-bot>=0.1.4
+Requires-Dist: praisonai-train>=0.1.4
+Requires-Dist: praisonai-browser>=0.1.4
+Requires-Dist: praisonai-mcp>=0.1.6
+Requires-Dist: praisonai-sandbox>=0.1.4
+Requires-Dist: praisonai-deploy>=0.1.4
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0
@@ -129,7 +129,8 @@ Provides-Extra: agno
 Requires-Dist: praisonai-frameworks[agno]>=0.1.8; extra == "agno"
 Requires-Dist: praisonai-tools>=0.1.0; extra == "agno"
 Provides-Extra: google-adk
-Requires-Dist: praisonai-frameworks[google-adk]>=0.1.8; extra == "google-adk"
+Requires-Dist: praisonai-frameworks>=0.1.8; extra == "google-adk"
+Requires-Dist: google-adk[extensions]<3,>=2.5; extra == "google-adk"
 Requires-Dist: praisonai-tools>=0.1.0; extra == "google-adk"
 Provides-Extra: pydantic-ai
 Requires-Dist: praisonai-frameworks[pydantic-ai]>=0.1.9; extra == "pydantic-ai"
@@ -247,6 +248,19 @@ curl -fsSL https://praison.ai/install.sh | bash
     <img src="https://img.shields.io/badge/Highlighted_by_Elon_Musk-000000?style=for-the-badge&logo=x&logoColor=white" alt="Highlighted by Elon Musk" />
   </a>
   <br>
+  <br>
+  <a href="https://github.com/MervinPraison/PraisonAI/releases/latest">
+    <img src="https://img.shields.io/badge/Download_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Download for macOS" />
+  </a>
+  &nbsp;&nbsp;
+  <a href="https://github.com/MervinPraison/PraisonAI/releases/latest">
+    <img src="https://img.shields.io/badge/Download_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Download for Windows" />
+  </a>
+  &nbsp;&nbsp;
+  <a href="https://github.com/MervinPraison/PraisonAI/releases/latest">
+    <img src="https://img.shields.io/badge/Download_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Download for Linux" />
+  </a>
+  <br>
 </div>
 
 <p align="center">
@@ -1311,13 +1325,39 @@ For other providers, see [Models docs](https://docs.praison.ai/docs/models).
 <summary><strong>How do I use a local model (Ollama)?</strong></summary>
 
 ```bash
-# Start Ollama server first
+# Start Ollama and pull a model
 ollama serve
+ollama pull llama3.2
+```
 
-# Set environment variable
-export OPENAI_BASE_URL=http://localhost:11434/v1
+```python
+from praisonaiagents import Agent
+
+agent = Agent(instructions="You are a helpful assistant", llm="ollama/llama3.2")
+agent.start("Why is the sky blue?")
 ```
 
+The `ollama/` prefix is what selects Ollama's handling — tool-call repair,
+tool-result formatting and the streaming rules small local models need. Or set
+it by environment instead:
+
+```bash
+export OPENAI_MODEL_NAME=ollama/llama3.2
+```
+
+Setting only `OPENAI_BASE_URL` is not enough: with no model named, the OpenAI
+default (`gpt-4o-mini`) is sent to Ollama, which answers
+`404 model 'gpt-4o-mini' not found`. Always name the model.
+
+Point at a non-default host with `base_url=` or `OLLAMA_HOST`:
+
+```python
+agent = Agent(instructions="...", llm="ollama/llama3.2", base_url="http://192.168.1.10:11434")
+```
+
+The same shape works for other local runtimes — `lm_studio/`, `vllm/` and
+`hosted_vllm/` with their server's `base_url`.
+
 See [Models docs](https://docs.praison.ai/docs/models) for more details.
 
 </details>

{praisonai-4.7.5 → praisonai-4.7.7}/PraisonAI.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PraisonAI
-Version: 4.7.5
+Version: 4.7.7
 Summary: PraisonAI is an AI Agents Framework with Self Reflection. PraisonAI application combines PraisonAI Agents, AutoGen, and CrewAI into a low-code solution for building and managing multi-agent LLM systems, focusing on simplicity, customisation, and efficient human-agent collaboration.
 Author: Mervin Praison
 License: MIT
@@ -11,14 +11,14 @@ Description-Content-Type: text/markdown
 Requires-Dist: rich>=13.7
 Requires-Dist: markdown>=3.5
 Requires-Dist: pyparsing>=3.0.0
-Requires-Dist: praisonaiagents>=1.7.3
-Requires-Dist: praisonai-code>=0.1.2
-Requires-Dist: praisonai-bot>=0.1.2
-Requires-Dist: praisonai-train>=0.1.2
-Requires-Dist: praisonai-browser>=0.1.2
-Requires-Dist: praisonai-mcp>=0.1.4
-Requires-Dist: praisonai-sandbox>=0.1.2
-Requires-Dist: praisonai-deploy>=0.1.2
+Requires-Dist: praisonaiagents>=1.7.5
+Requires-Dist: praisonai-code>=0.1.4
+Requires-Dist: praisonai-bot>=0.1.4
+Requires-Dist: praisonai-train>=0.1.4
+Requires-Dist: praisonai-browser>=0.1.4
+Requires-Dist: praisonai-mcp>=0.1.6
+Requires-Dist: praisonai-sandbox>=0.1.4
+Requires-Dist: praisonai-deploy>=0.1.4
 Requires-Dist: python-dotenv>=0.19.0
 Requires-Dist: litellm<2,>=1.83.14
 Requires-Dist: PyYAML>=6.0
@@ -129,7 +129,8 @@ Provides-Extra: agno
 Requires-Dist: praisonai-frameworks[agno]>=0.1.8; extra == "agno"
 Requires-Dist: praisonai-tools>=0.1.0; extra == "agno"
 Provides-Extra: google-adk
-Requires-Dist: praisonai-frameworks[google-adk]>=0.1.8; extra == "google-adk"
+Requires-Dist: praisonai-frameworks>=0.1.8; extra == "google-adk"
+Requires-Dist: google-adk[extensions]<3,>=2.5; extra == "google-adk"
 Requires-Dist: praisonai-tools>=0.1.0; extra == "google-adk"
 Provides-Extra: pydantic-ai
 Requires-Dist: praisonai-frameworks[pydantic-ai]>=0.1.9; extra == "pydantic-ai"
@@ -247,6 +248,19 @@ curl -fsSL https://praison.ai/install.sh | bash
     <img src="https://img.shields.io/badge/Highlighted_by_Elon_Musk-000000?style=for-the-badge&logo=x&logoColor=white" alt="Highlighted by Elon Musk" />
   </a>
   <br>
+  <br>
+  <a href="https://github.com/MervinPraison/PraisonAI/releases/latest">
+    <img src="https://img.shields.io/badge/Download_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Download for macOS" />
+  </a>
+  &nbsp;&nbsp;
+  <a href="https://github.com/MervinPraison/PraisonAI/releases/latest">
+    <img src="https://img.shields.io/badge/Download_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Download for Windows" />
+  </a>
+  &nbsp;&nbsp;
+  <a href="https://github.com/MervinPraison/PraisonAI/releases/latest">
+    <img src="https://img.shields.io/badge/Download_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Download for Linux" />
+  </a>
+  <br>
 </div>
 
 <p align="center">
@@ -1311,13 +1325,39 @@ For other providers, see [Models docs](https://docs.praison.ai/docs/models).
 <summary><strong>How do I use a local model (Ollama)?</strong></summary>
 
 ```bash
-# Start Ollama server first
+# Start Ollama and pull a model
 ollama serve
+ollama pull llama3.2
+```
 
-# Set environment variable
-export OPENAI_BASE_URL=http://localhost:11434/v1
+```python
+from praisonaiagents import Agent
+
+agent = Agent(instructions="You are a helpful assistant", llm="ollama/llama3.2")
+agent.start("Why is the sky blue?")
 ```
 
+The `ollama/` prefix is what selects Ollama's handling — tool-call repair,
+tool-result formatting and the streaming rules small local models need. Or set
+it by environment instead:
+
+```bash
+export OPENAI_MODEL_NAME=ollama/llama3.2
+```
+
+Setting only `OPENAI_BASE_URL` is not enough: with no model named, the OpenAI
+default (`gpt-4o-mini`) is sent to Ollama, which answers
+`404 model 'gpt-4o-mini' not found`. Always name the model.
+
+Point at a non-default host with `base_url=` or `OLLAMA_HOST`:
+
+```python
+agent = Agent(instructions="...", llm="ollama/llama3.2", base_url="http://192.168.1.10:11434")
+```
+
+The same shape works for other local runtimes — `lm_studio/`, `vllm/` and
+`hosted_vllm/` with their server's `base_url`.
+
 See [Models docs](https://docs.praison.ai/docs/models) for more details.
 
 </details>

{praisonai-4.7.5 → praisonai-4.7.7}/PraisonAI.egg-info/SOURCES.txt

@@ -33,17 +33,6 @@ praisonai/upload_vision.py
 praisonai/version.py
 praisonai/_dev/__init__.py
 praisonai/_dev/api_md.py
-praisonai/_dev/parity/__init__.py
-praisonai/_dev/parity/docs_extractor.py
-praisonai/_dev/parity/docs_generator.py
-praisonai/_dev/parity/generator.py
-praisonai/_dev/parity/python_docs_extractor.py
-praisonai/_dev/parity/python_extractor.py
-praisonai/_dev/parity/rust_docs_extractor.py
-praisonai/_dev/parity/rust_extractor.py
-praisonai/_dev/parity/topic_normalizer.py
-praisonai/_dev/parity/ts_docs_extractor.py
-praisonai/_dev/parity/typescript_extractor.py
 praisonai/acp/__init__.py
 praisonai/acp/config.py
 praisonai/acp/safe_edit.py
@@ -497,7 +486,6 @@ praisonai/standardise/discovery.py
 praisonai/standardise/drift.py
 praisonai/standardise/engine.py
 praisonai/standardise/example_verifier.py
-praisonai/standardise/manifest.py
 praisonai/standardise/models.py
 praisonai/standardise/reports.py
 praisonai/standardise/templates.py

{praisonai-4.7.5 → praisonai-4.7.7}/PraisonAI.egg-info/requires.txt

@@ -1,14 +1,14 @@
 rich>=13.7
 markdown>=3.5
 pyparsing>=3.0.0
-praisonaiagents>=1.7.3
-praisonai-code>=0.1.2
-praisonai-bot>=0.1.2
-praisonai-train>=0.1.2
-praisonai-browser>=0.1.2
-praisonai-mcp>=0.1.4
-praisonai-sandbox>=0.1.2
-praisonai-deploy>=0.1.2
+praisonaiagents>=1.7.5
+praisonai-code>=0.1.4
+praisonai-bot>=0.1.4
+praisonai-train>=0.1.4
+praisonai-browser>=0.1.4
+praisonai-mcp>=0.1.6
+praisonai-sandbox>=0.1.4
+praisonai-deploy>=0.1.4
 python-dotenv>=0.19.0
 litellm<2,>=1.83.14
 PyYAML>=6.0
@@ -158,7 +158,8 @@ requests>=2.31.0
 praisonai-bot[gateway]
 
 [google-adk]
-praisonai-frameworks[google-adk]>=0.1.8
+praisonai-frameworks>=0.1.8
+google-adk[extensions]<3,>=2.5
 praisonai-tools>=0.1.0
 
 [gradio]

{praisonai-4.7.5 → praisonai-4.7.7}/README.md

@@ -35,6 +35,19 @@ curl -fsSL https://praison.ai/install.sh | bash
     <img src="https://img.shields.io/badge/Highlighted_by_Elon_Musk-000000?style=for-the-badge&logo=x&logoColor=white" alt="Highlighted by Elon Musk" />
   </a>
   <br>
+  <br>
+  <a href="https://github.com/MervinPraison/PraisonAI/releases/latest">
+    <img src="https://img.shields.io/badge/Download_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Download for macOS" />
+  </a>
+  &nbsp;&nbsp;
+  <a href="https://github.com/MervinPraison/PraisonAI/releases/latest">
+    <img src="https://img.shields.io/badge/Download_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Download for Windows" />
+  </a>
+  &nbsp;&nbsp;
+  <a href="https://github.com/MervinPraison/PraisonAI/releases/latest">
+    <img src="https://img.shields.io/badge/Download_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Download for Linux" />
+  </a>
+  <br>
 </div>
 
 <p align="center">
@@ -1099,13 +1112,39 @@ For other providers, see [Models docs](https://docs.praison.ai/docs/models).
 <summary><strong>How do I use a local model (Ollama)?</strong></summary>
 
 ```bash
-# Start Ollama server first
+# Start Ollama and pull a model
 ollama serve
+ollama pull llama3.2
+```
 
-# Set environment variable
-export OPENAI_BASE_URL=http://localhost:11434/v1
+```python
+from praisonaiagents import Agent
+
+agent = Agent(instructions="You are a helpful assistant", llm="ollama/llama3.2")
+agent.start("Why is the sky blue?")
 ```
 
+The `ollama/` prefix is what selects Ollama's handling — tool-call repair,
+tool-result formatting and the streaming rules small local models need. Or set
+it by environment instead:
+
+```bash
+export OPENAI_MODEL_NAME=ollama/llama3.2
+```
+
+Setting only `OPENAI_BASE_URL` is not enough: with no model named, the OpenAI
+default (`gpt-4o-mini`) is sent to Ollama, which answers
+`404 model 'gpt-4o-mini' not found`. Always name the model.
+
+Point at a non-default host with `base_url=` or `OLLAMA_HOST`:
+
+```python
+agent = Agent(instructions="...", llm="ollama/llama3.2", base_url="http://192.168.1.10:11434")
+```
+
+The same shape works for other local runtimes — `lm_studio/`, `vllm/` and
+`hosted_vllm/` with their server's `base_url`.
+
 See [Models docs](https://docs.praison.ai/docs/models) for more details.
 
 </details>

{praisonai-4.7.5 → praisonai-4.7.7}/praisonai/__main__.py

@@ -85,6 +85,32 @@ _global_option_names_lock = threading.Lock()
 _LEGACY_COLLIDING_SHORT_OPTS = frozenset({"-s", "-f"})
 
 
+def _introspect_option_names(command):
+    """Derive ``(all_opts, value_opts)`` from a Click command's parameters.
+
+    Single owner for the parse loop shared by :func:`_get_run_option_names` and
+    :func:`_get_global_option_names`; ``all_opts`` is every long/short option
+    string and ``value_opts`` is the non-flag subset that consumes a value.
+    """
+    all_opts = set()
+    value_opts = set()
+    for param in command.params:
+        is_flag = getattr(param, "is_flag", False) or getattr(
+            param, "is_bool_flag", False
+        )
+        for opt in getattr(param, "opts", []):
+            if opt.startswith("-"):
+                all_opts.add(opt)
+                if not is_flag:
+                    value_opts.add(opt)
+        # Secondary opts are the negated forms of bool flags
+        # (e.g. ``--no-stream``); never value-consuming.
+        for opt in getattr(param, "secondary_opts", []):
+            if opt.startswith("-"):
+                all_opts.add(opt)
+    return all_opts, value_opts
+
+
 def _get_run_option_names():
     """Return the option names accepted by the Typer ``run`` command.
 
@@ -110,22 +136,7 @@ def _get_run_option_names():
             from typer.main import get_command as _get_command
 
             command = _get_command(run_app)
-            all_opts = set()
-            value_opts = set()
-            for param in command.params:
-                is_flag = getattr(param, "is_flag", False) or getattr(
-                    param, "is_bool_flag", False
-                )
-                for opt in getattr(param, "opts", []):
-                    if opt.startswith("-"):
-                        all_opts.add(opt)
-                        if not is_flag:
-                            value_opts.add(opt)
-                # Secondary opts are the negated forms of bool flags
-                # (e.g. ``--no-stream``); never value-consuming.
-                for opt in getattr(param, "secondary_opts", []):
-                    if opt.startswith("-"):
-                        all_opts.add(opt)
+            all_opts, value_opts = _introspect_option_names(command)
         except Exception:
             # Introspection depends only on the static command definition, so a
             # failure here is structural — cache it (as ``False``) to avoid
@@ -157,20 +168,7 @@ def _get_global_option_names():
             from typer.main import get_command as _get_command
 
             command = _get_command(root_app)
-            all_opts = set()
-            value_opts = set()
-            for param in command.params:
-                is_flag = getattr(param, "is_flag", False) or getattr(
-                    param, "is_bool_flag", False
-                )
-                for opt in getattr(param, "opts", []):
-                    if opt.startswith("-"):
-                        all_opts.add(opt)
-                        if not is_flag:
-                            value_opts.add(opt)
-                for opt in getattr(param, "secondary_opts", []):
-                    if opt.startswith("-"):
-                        all_opts.add(opt)
+            all_opts, value_opts = _introspect_option_names(command)
         except Exception:
             _global_option_names_cache = False
             return None

{praisonai-4.7.5 → praisonai-4.7.7}/praisonai/_async_bridge.py

@@ -9,15 +9,66 @@ import asyncio
 import atexit
 import contextlib
 import contextvars
+import enum
+import inspect
+import logging
 import os
 import threading
+import weakref
 import concurrent.futures
 from concurrent.futures import CancelledError as FutureCancelledError, Future
-from typing import Awaitable, Iterator, Optional, TypeVar
+from typing import Any, Awaitable, Iterator, Optional, TypeVar
+
+logger = logging.getLogger(__name__)
 
 T = TypeVar("T")
 
-_DEFAULT_TIMEOUT = float(os.environ.get("PRAISONAI_RUN_SYNC_TIMEOUT", "300"))
+
+class _Unset:
+    """Sentinel for an *omitted* timeout argument.
+
+    Distinguishes "caller did not pass a timeout" (resolve the configured
+    default via :func:`_default_timeout`) from an explicit ``timeout=None``
+    (an intentional request for an *unbounded* wait). The scheduler bridges
+    (``integration/bridges/schedules_runner.py``, ``cli/commands/schedule.py``)
+    rely on the latter so a long-running claimed job is never cancelled after
+    the 300s default.
+    """
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid only
+        return "<unset>"
+
+
+_UNSET = _Unset()
+
+
+def _resolve_timeout(timeout: "float | None | _Unset") -> Optional[float]:
+    """Map an omitted timeout to the configured default, preserving explicit None.
+
+    - ``_UNSET`` (argument omitted) → :func:`_default_timeout` (e.g. 300s).
+    - explicit ``None`` → ``None`` (unbounded wait; caller opted in).
+    - a number → itself.
+    """
+    if isinstance(timeout, _Unset):
+        return _default_timeout()
+    return timeout
+
+
+def _default_timeout() -> float:
+    """Resolve the default run_sync timeout lazily, per call.
+
+    Read at call time (not import time) so a malformed ``PRAISONAI_RUN_SYNC_TIMEOUT``
+    cannot crash ``import praisonai`` with an unrelated ``ValueError``, and so a
+    value set after import (dotenv loaded late, per-request reconfig) is honoured.
+    Falls back to 300s on a malformed value.
+    """
+    raw = os.environ.get("PRAISONAI_RUN_SYNC_TIMEOUT", "300")
+    try:
+        return float(raw)
+    except ValueError:
+        return 300.0
 
 class AsyncBridge:
     """Per-instance async runner. The module-level `run_sync()` keeps the
@@ -38,6 +89,9 @@ class AsyncBridge:
         # lock by ``get()``/``submit()`` so ``_spawn_locked()`` can verify the
         # *caller* (not merely *someone*) owns the lock.
         self._lock_owner: int | None = None
+        # The shared default registers its atexit teardown lazily, on first use,
+        # so a bare ``import praisonai`` installs no process-wide hook.
+        self._atexit_registered = False
 
     def _spawn_locked(self) -> asyncio.AbstractEventLoop:
         """Create the loop+thread; caller must hold ``self._lock``.
@@ -74,6 +128,13 @@ class AsyncBridge:
                 daemon=True,
             )
             self._thread.start()
+            # Register the process-exit teardown lazily and only for the shared
+            # default. Doing it here (first real use) rather than at import keeps
+            # ``import praisonai`` free of an unrequested atexit hook that would
+            # compete with hosts like Django/Airflow/Streamlit for shutdown order.
+            if not self._atexit_registered and self is globals().get("_BG"):
+                atexit.register(self.shutdown)
+                self._atexit_registered = True
         return self._loop
 
     def get(self) -> asyncio.AbstractEventLoop:
@@ -94,7 +155,11 @@ class AsyncBridge:
             finally:
                 self._lock_owner = None
 
-    def run_sync(self, coro: Awaitable[T], *, timeout: float | None = _DEFAULT_TIMEOUT) -> T:
+    def run_sync(
+        self, coro: Awaitable[T], *, timeout: "float | None | _Unset" = _UNSET
+    ) -> T:
+        # Omitted → configured default; explicit ``None`` → unbounded wait.
+        timeout = _resolve_timeout(timeout)
         try:
             asyncio.get_running_loop()
         except RuntimeError:
@@ -245,19 +310,18 @@ def scoped_bridge(bridge: Optional[AsyncBridge] = None) -> Iterator[AsyncBridge]
 def _shutdown_default() -> None:
     """Private process-exit hook: tear down the shared default bridge.
 
-    Registered with :mod:`atexit`. This is the ONLY sanctioned way the shared
-    default is shut down; it is deliberately absent from the public module
-    surface so a single caller cannot terminate async work for the whole
-    process. Embedders needing explicit lifecycle control own their own
-    :class:`AsyncBridge` instance.
+    Registered with :mod:`atexit` lazily (on the shared default's first real use
+    in :meth:`AsyncBridge._spawn_locked`), not at import, so a bare
+    ``import praisonai`` installs no process-wide hook. This is the ONLY
+    sanctioned way the shared default is shut down; it is deliberately absent
+    from the public module surface so a single caller cannot terminate async
+    work for the whole process. Embedders needing explicit lifecycle control own
+    their own :class:`AsyncBridge` instance.
     """
     _BG.shutdown()
 
 
-atexit.register(_shutdown_default)
-
-
-def run_sync(coro: Awaitable[T], *, timeout: float | None = _DEFAULT_TIMEOUT) -> T:
+def run_sync(coro: Awaitable[T], *, timeout: "float | None | _Unset" = _UNSET) -> T:
     """
     Run a coroutine synchronously using the background loop.
     
@@ -282,7 +346,7 @@ def run_sync(coro: Awaitable[T], *, timeout: float | None = _DEFAULT_TIMEOUT) ->
 def run_sync_or_offload(
     coro: Awaitable[T],
     *,
-    timeout: float | None = _DEFAULT_TIMEOUT,
+    timeout: "float | None | _Unset" = _UNSET,
     thread_name: str = "praisonai-sync-offload",
 ) -> T:
     """Run ``coro`` to completion from *any* calling context.
@@ -303,6 +367,8 @@ def run_sync_or_offload(
     (it fails loudly inside a loop). Async callers should ``await``
     :func:`arun_sync_or_offload`, which never blocks the loop.
     """
+    # Omitted → configured default; explicit ``None`` → unbounded wait.
+    timeout = _resolve_timeout(timeout)
     try:
         asyncio.get_running_loop()
     except RuntimeError:
@@ -383,7 +449,7 @@ def run_sync_or_offload(
 async def arun_sync_or_offload(
     coro: Awaitable[T],
     *,
-    timeout: float | None = _DEFAULT_TIMEOUT,
+    timeout: "float | None | _Unset" = _UNSET,
 ) -> T:
     """Awaitable sibling of :func:`run_sync_or_offload` for async callers.
 
@@ -397,6 +463,9 @@ async def arun_sync_or_offload(
     ``asyncio.new_event_loop()``), so a caller-installed :func:`scoped_bridge`
     binding still wins and per-loop connection pools are preserved.
     """
+    # Omitted → configured default; explicit ``None`` → unbounded wait
+    # (``asyncio.wait_for(..., timeout=None)`` waits indefinitely).
+    timeout = _resolve_timeout(timeout)
     fut = _default_bridge().submit(coro)
     wrapped = asyncio.wrap_future(fut)
     try:
@@ -404,3 +473,72 @@ async def arun_sync_or_offload(
     except (asyncio.TimeoutError, asyncio.CancelledError):
         fut.cancel()
         raise
+
+
+class DispatchKind(str, enum.Enum):
+    """How a sync caller consumes the result of a (possibly async) store op.
+
+    Making read-vs-write intent explicit at the *call site* removes the need for
+    a name-string allow-list (the old ``_READ_OPS`` frozenset) that silently
+    dropped a new read-shaped method's return value under a running loop.
+    """
+
+    READ = "read"    #: caller consumes the returned value (never fire-and-forget)
+    WRITE = "write"  #: caller only cares that it eventually completes
+
+
+def dispatch_maybe_awaitable(
+    value: Any,
+    *,
+    kind: DispatchKind,
+    tracker: "weakref.WeakSet | None" = None,
+    tracker_lock: "threading.Lock | None" = None,
+    op_name: str = "op",
+) -> Any:
+    """Single owner of "a sync call may return a coroutine; run it correctly".
+
+    This consolidates the submit/track/callback scaffolding that lifecycle hooks
+    would otherwise hand-roll per op. Behaviour:
+
+    - **Not awaitable**: returned as-is.
+    - **No running loop**: block on the shared bridge via :func:`run_sync`.
+    - **Running loop + READ**: route through :func:`run_sync_or_offload`, which
+      returns the value on a sync path and fails loudly inside a loop instead of
+      corrupting a read-modify-write with a silent ``None``.
+    - **Running loop + WRITE**: submit to the active bridge as tracked
+      fire-and-forget (uuid-keyed store writes are idempotent, so completing them
+      slightly later is safe), attach a warning done-callback, and return
+      ``None``.
+
+    Args:
+        value: The result of calling the store method (may be a coroutine).
+        kind: :class:`DispatchKind.READ` or :class:`DispatchKind.WRITE`.
+        tracker: Optional ``WeakSet`` of in-flight futures so a ``close()`` path
+            can flush them; only used on the running-loop WRITE branch.
+        tracker_lock: Lock guarding ``tracker``.
+        op_name: Human-readable op name for log/thread naming.
+    """
+    if not inspect.isawaitable(value):
+        return value
+
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return run_sync(value)
+
+    if kind is DispatchKind.READ:
+        return run_sync_or_offload(value, thread_name=f"praisonai-db-read-{op_name}")
+
+    fut = current_bridge().submit(value)
+    if tracker is not None and tracker_lock is not None:
+        with tracker_lock:
+            tracker.add(fut)
+
+    def _on_done(f, name=op_name):
+        try:
+            f.result()
+        except Exception:
+            logger.warning("Deferred %s failed", name, exc_info=True)
+
+    fut.add_done_callback(_on_done)
+    return None