Wrapper gaps in src/praisonai/praisonai: capabilities sync/async twin drift (moderation default already diverged), A2U/agent_invoke process-global singletons, and `integration` vs `integrations` namespace collision
I maintainer di solito rispondono entro 1 giorno
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 15/100
Direzione di ricerca
The async and sync moderate/amoderate defaults differ at src/praisonai/praisonai/capabilities/moderations.py lines 17-23 and 96-104; that mismatch is the one concrete bug. The wider refactor spans the sync/async twins across capabilities/ (indexed in capabilities/__init__.py), the _async_bridge.py helper, and the integration/ vs integrations/ namespace split, which needs a maintainer decision first. Done means one default and one body per capability, plus an agreed namespace outcome.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Overview
Deep review of src/praisonai/praisonai/ against the project's core philosophy — Simpler · More extensible · Faster · Agent-centric — and its engineering principles (DRY · Protocol-driven core · No perf impact · Multi-agent + async safe by default · 3-way surface: CLI/YAML/Python).
Three concrete gaps stand out. Each one has been validated against the code in the current branch — file paths, line numbers and reproduction snippets are given verbatim, followed by a proposed fix with a code example. Scope is intentionally src/praisonai/praisonai/ only; this excludes documentation, tests, coverage, file sizes and line counts.
1. The capabilities/ module ships every LLM operation as hand-copied sync + async twins — and the defaults have already drifted
Files: src/praisonai/praisonai/capabilities/*.py (23 modules; the pattern is systemic)
The gap
Every public operation in capabilities/ is written as a pair: a sync function foo(…) and an async twin afoo(…) whose body is near-byte-identical and differs only in one line (litellm.X(...) vs await litellm.aX(...)). The twins share no implementation seam; they are duplicated end-to-end — argument block, call-kwargs assembly, response parsing, result-object construction. The whole surface is enumerated once in capabilities/__init__.py:183 (_ATTR_TO_MODULE) and goes:
| file | sync | async |
|---|---|---|
capabilities/audio.py |
transcribe, speech |
atranscribe, aspeech |
capabilities/images.py |
image_generate, image_edit |
aimage_generate, aimage_edit |
capabilities/completions.py |
chat_completion, text_completion |
achat_completion, atext_completion |
capabilities/moderations.py |
moderate |
amoderate |
capabilities/messages.py, rag.py, rerank.py, ocr.py, assistants.py, fine_tuning.py, responses.py, passthrough.py, search.py, videos.py, vector_stores.py, vector_store_files.py, container_files.py, batches.py, files.py, realtime.py, skills.py, mcp.py, guardrails.py, a2a.py |
sync half | async half |
Drift already present (visible bug)
The predicted-and-now-arrived consequence: the sync and async defaults have fallen out of sync.
src/praisonai/praisonai/capabilities/moderations.py:17-23 (sync):
def moderate(
input: Union[str, List[str]],
model: str = "omni-moderation-latest", # ← modern default
timeout: float = 600.0,
...
) -> List[ModerationResult]:
src/praisonai/praisonai/capabilities/moderations.py:96-104 (async twin):
async def amoderate(
input: Union[str, List[str]],
model: str = "text-moderation-latest", # ← legacy default, never updated
timeout: float = 600.0,
...
) -> List[ModerationResult]:
Same operation, two different default models. A user who calls moderate("…") gets OpenAI's current omni-moderation-latest; the same user calling await amoderate("…") silently gets the older, less capable text-moderation-latest. The 3-way surface rule ("each feature runs CLI / YAML / Python") is violated at the Python layer alone — the async branch and the sync branch of the same feature now behave differently.
The rest of the body is the drift risk the moderations default has already realised. Side-by-side on moderate vs amoderate (same file, 76 lines later):
moderations.py:49-93 (sync):
import litellm
call_kwargs = {
'input': input,
'model': model,
'timeout': timeout,
}
if api_key:
call_kwargs['api_key'] = api_key
if api_base:
call_kwargs['api_base'] = api_base
call_kwargs.update(kwargs)
if metadata:
call_kwargs['metadata'] = metadata
response = litellm.moderation(**call_kwargs)
results = []
if hasattr(response, 'results'):
for item in response.results:
categories = {}
category_scores = {}
if hasattr(item, 'categories'):
for cat_name in dir(item.categories):
if not cat_name.startswith('_'):
categories[cat_name] = getattr(item.categories, cat_name, False)
...
results.append(ModerationResult(
flagged=getattr(item, 'flagged', False),
categories=categories,
category_scores=category_scores,
model=model,
metadata=metadata or {},
))
return results
moderations.py:110-154 (async): the same ~45-line body copied verbatim, differing only in response = await litellm.amoderation(**call_kwargs).
The pattern repeats in every file above — completions.py:60-123 (chat_completion) vs :144-205 (achat_completion), audio.py:78-129 vs :150-199, images.py four twins, etc.
Why it matters
- DRY: every bug fix, every retry/timeout tweak, every new provider-specific
metadatafield has to be mirrored by hand into two files. One side gets forgotten (moderations proves it). - "Lightweight wrapper":
capabilities/is 23 modules whose contents are ~50% duplicated prose. The eager-import cost is still mitigated bycapabilities/__init__.py's lazy__getattr__, but the maintenance surface sitting in the shipped SDK is twice what it needs to be. - "3-way surface rule": CLI/YAML/Python must behave identically. Here the Python surface alone has two faces: calling
moderatethrough the sync entry point andamoderatethrough the async entry point land on different models. The async side is now objectively worse without any user action.
Note: the fix pattern already exists in the same directory — capabilities/embeddings.py was collapsed to re-export the canonical implementation from the Core SDK and that file explicitly flags why ("praisonai.EmbeddingResult and praisonai.capabilities.EmbeddingResult were two different classes — so isinstance(result, EmbeddingResult) depended on which import a caller happened to pick"). Everything else in capabilities/ is a near-identical case waiting for the same treatment.
Proposed fix — single async implementation + a tiny sync adapter
For each capability, keep one async implementation. The sync entry point reduces to a run-through-the-bridge adapter.
# capabilities/moderations.py (post-collapse, ~55 lines total, no drift surface)
from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional, Union
from .._async_bridge import run_sync
# Keep the single result type here (it is 7 lines; a core-SDK home is also fine)
@dataclass
class ModerationResult:
flagged: bool
categories: Dict[str, bool] = field(default_factory=dict)
category_scores: Dict[str, float] = field(default_factory=dict)
model: Optional[str] = None
metadata: Dict[str, Any] = field(default_factory=dict)
# One default. One body. Both entry points go through it.
_DEFAULT_MODEL = "omni-moderation-latest"
async def amoderate(
input: Union[str, List[str]],
model: str = _DEFAULT_MODEL,
timeout: float = 600.0,
api_key: Optional[str] = None,
api_base: Optional[str] = None,
metadata: Optional[Dict[str, Any]] = None,
**kwargs,
) -> List[ModerationResult]:
import litellm
call_kwargs = {'input': input, 'model': model, 'timeout': timeout}
if api_key: call_kwargs['api_key'] = api_key
if api_base: call_kwargs['api_base'] = api_base
call_kwargs.update(kwargs)
if metadata: call_kwargs['metadata'] = metadata
response = await litellm.amoderation(**call_kwargs)
return _results_from_response(response, model, metadata)
def moderate(*args, **kwargs) -> List[ModerationResult]:
"""Sync facade — one body, no drift."""
return run_sync(amoderate(*args, **kwargs))
def _results_from_response(response, model, metadata) -> List[ModerationResult]:
results: list = []
if hasattr(response, 'results'):
for item in response.results:
categories = {}
category_scores = {}
if hasattr(item, 'categories'):
for cat_name in dir(item.categories):
if not cat_name.startswith('_'):
categories[cat_name] = getattr(item.categories, cat_name, False)
if hasattr(item, 'category_scores'):
for cat_name in dir(item.category_scores):
if not cat_name.startswith('_'):
category_scores[cat_name] = getattr(item.category_scores, cat_name, 0.0)
results.append(ModerationResult(
flagged=getattr(item, 'flagged', False),
categories=categories,
category_scores=category_scores,
model=model,
metadata=metadata or {},
))
return results
The wrapper already owns praisonai._async_bridge.run_sync — the same bridge the scheduler and generate_crew_and_kickoff use for exactly this purpose. Routing through it means:
- one default, one argument block, one response-parser per capability;
- a stuck provider cannot deadlock, because
_async_bridgeruns the coroutine on its own loop + daemon thread (_async_bridge.py:109-137); - the moderation drift and every future one goes away by construction.
The same shape applies file by file: completions.py, audio.py, images.py, …; each collapses from ~200 LOC + two defaults to ~100 LOC + one.
2. praisonai.integration (singular — UI host shims) and praisonai.integrations (plural — external CLI/managed-agent plugin registry) are two unrelated top-level namespaces that differ only in a single character
Files:
src/praisonai/praisonai/integration/__init__.py+ 4 modulessrc/praisonai/praisonai/integrations/__init__.py+ 15 modules
The gap
Both exist, both are first-class entries under praisonai.*, both are actively imported. They have no overlap in purpose:
-
praisonai.integration(singular) — a thin 7-linesys.modules-swap shim for the PraisonAIUI host bootstrap (host_app,gateway_host,context_files,pages). All files delegate topraisonai_bot.integration.*. Fromintegration/host_app.py:1-9:"""Backward-compatibility shim → :mod:`praisonai_bot.integration.host_app`.""" import sys as _sys from praisonai._bootstrap import ensure_praisonai_bot ensure_praisonai_bot() import praisonai_bot.integration.host_app as _impl _sys.modules[__name__] = _impl -
praisonai.integrations(plural) — the real external-agent plugin registry: Claude Code / Codex / Gemini / Cursor CLIs, Anthropic managed agents, hosted/local/sandboxed agents, backed by an entry-point plugin grouppraisonai.integrations. Fromintegrations/__init__.py:""" PraisonAI Integrations - External CLI tool and managed agent integrations. ... Third-party plugins:: [project.entry-points."praisonai.integrations"] acme = "acme_praison:AcmeIntegration" """
Both are actually imported in the same tree today — e.g. inside the UI preset packages:
src/praisonai/praisonai/ui_bot/default_app.py:10:
from praisonai.integration.host_app import UIPreset, build_ui_app # singular (UI host)
src/praisonai/praisonai/ui/_external_agents.py:23:
from praisonai.integrations.registry import external_agent_catalog # plural (CLI plugins)
src/praisonai/praisonai/cli/legacy/dispatch/argparse_builder.py:298:
from praisonai.integrations.registry import list_external_agents # plural
src/praisonai/praisonai/ui_chat/default_app.py:14:
from praisonai.integration.host_app import UIPreset, build_ui_app # singular
Why it matters
- "Easy for non-developers / few lines of code": nothing about the names
integrationvsintegrationstells a caller which one hosts UI bootstrap and which one hosts external CLI tool plugins. A missedsresolves to a shim module that doessys.modules[__name__] = <something totally different>; a user who typos either direction sees "AttributeError: modulepraisonai.integrationshas no attributehost_app" (or the mirror) and has to grep the source tree. - "Simpler · More extensible": the public namespace carries two load-bearing top-level packages separated only by one letter. Every example, every doc snippet, every stack trace has to be read carefully, and search tools make this worse —
grep "integration"returns both. - "Protocol-driven core / lightweight wrapper": one of the two (
integration/) is 100% shim — nothing lives there, it only forwards topraisonai_bot.integration. Keeping the shim is fine for backward compatibility; keeping it under a one-letter-different name from the real plugin registry is not.
This isn't about renaming for aesthetics — the risk is a real import going to the wrong module, especially in third-party docs or AI-assisted code generation that gets a letter wrong.
Proposed fix — rename the singular shim to a non-colliding path
Move the UI-host shim to a name that cannot be confused with the plugin registry (ui_host/, host/, or aiui_host/), keep praisonai.integration alive as a deprecated redirect for one release cycle:
# NEW: src/praisonai/praisonai/ui_host/__init__.py
"""PraisonAI ↔ PraisonAIUI integration layer (Pattern B/C host bootstrap).
Canonical module. The old spelling ``praisonai.integration`` is a deprecated
one-release alias; new code should import from ``praisonai.ui_host``.
"""
from .host_app import (
build_host_app, configure_host, create_host_app,
is_legacy_host, setup_bridges,
)
__all__ = [
"build_host_app", "configure_host", "create_host_app",
"is_legacy_host", "setup_bridges", "run_integrated_gateway",
]
def __getattr__(name):
if name == "run_integrated_gateway":
from .gateway_host import run_integrated_gateway
return run_integrated_gateway
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
# REPLACE: src/praisonai/praisonai/integration/__init__.py
"""Deprecated alias for :mod:`praisonai.ui_host`.
``praisonai.integration`` (singular) was easy to confuse with
``praisonai.integrations`` (plural, the external CLI/managed-agent plugin
registry). Import from ``praisonai.ui_host`` instead.
"""
import warnings as _warnings
import sys as _sys
from praisonai import ui_host as _impl # noqa: F401
_warnings.warn(
"praisonai.integration is deprecated; import from praisonai.ui_host instead",
DeprecationWarning, stacklevel=2,
)
_sys.modules[__name__] = _impl
Each caller then migrates at its own pace (ui_bot/default_app.py, ui_chat/default_app.py, ui_realtime/default_app.py, ui_dashboard/default_app.py, ui_agents/default_app.py, __init__.py build_host_app / configure_host / run_integrated_gateway lazy getters, …). Searches disambiguate immediately.
The same reasoning applies to praisonai.adapters (RAG readers/vector-stores/rerankers) vs praisonai.framework_adapters (CrewAI / AutoGen / PraisonAI framework adapters) — both are top-level *adapters packages for unrelated subsystems — but there the names are not a one-letter typo apart and the risk is lower. The singular/plural integration[s] pair is the acute one.
3. The A2U event bus and the agent_invoke free-function fallback still land on a module-level singleton — multi-tenant isolation is advertised but opt-in
Files:
src/praisonai/praisonai/endpoints/a2u_server.pysrc/praisonai/praisonai/api/agent_invoke.py
The gap
This is a specific follow-up to #5163 (closed): PR #5212 fixed the symmetric scoped_bridge on agenerate_crew_and_kickoff, which was the loudest half of the issue. The registry/event-bus half — the second gap called out in #5163's body — is still present on this branch. Two concrete call sites:
(a) src/praisonai/praisonai/endpoints/a2u_server.py:390-402:
# Global event bus instance
_event_bus_lock = threading.Lock()
_event_bus: Optional[A2UEventBus] = None
def get_event_bus() -> A2UEventBus:
"""Get or create the global event bus."""
global _event_bus
if _event_bus is None:
with _event_bus_lock:
if _event_bus is None:
_event_bus = A2UEventBus()
return _event_bus
And a2u_server.py:637 (get_event_bus().publish_sync(event, stream_name)) which means every call site that doesn't pass event_bus= emits onto the process-global bus. Two tenants in one interpreter — e.g. two AgentOS hosts, or a scheduled task + a serve gateway — see each other's agent_started / agent_finished / token_streamed events.
(b) src/praisonai/praisonai/api/agent_invoke.py:198-227:
_default_registry = AgentRegistry()
def _registry_dependency() -> AgentRegistry:
"""Which ``AgentRegistry`` serves this request?
Returns the process-default registry by default, but is overridable via
``app.dependency_overrides[_registry_dependency] = ...`` so an ``AgentOS`` /
``serve`` host can bind its own registry per app instance and get real
per-tenant isolation through the router (not just the free functions).
"""
return _default_registry
def register_agent(agent_id: str, agent: Any,
*, registry: Optional[AgentRegistry] = None) -> None:
"""Register an agent for invocation via API."""
(registry or _default_registry).register(agent_id, agent)
def get_agent(agent_id: str,
*, registry: Optional[AgentRegistry] = None) -> Optional[Any]:
"""Get a registered agent by ID."""
return (registry or _default_registry).get(agent_id)
The class docstring at :161-167 promises per-tenant isolation, but the free-function entry points (which anything outside the FastAPI router — scheduled jobs, bot handlers, Python callers, tests — uses) all fall through (registry or _default_registry) to the process-global dict. Call register_agent("assistant", …) from tenant A and tenant B's lookup under the same id returns tenant A's agent.
Why it matters
- "Multi-agent + async safe by default": the "safe" path is the one that requires every caller to thread
registry=/event_bus=through every helper. The default path is the unsafe one. - "Safe by default, hard to misuse": the exact inversion of the stated pillar. The free-function registry/event-bus is the convenience surface documented in
AgentRegistry.__doc__, and the convenience surface shares state across tenants. - The scoped-bridge fix in #5212 already proved a scoped
contextvarsseam works for the wrapper's isolation story. Extending it to the two singletons left behind closes the loop.
Proposed fix — scoped bindings via contextvars, with the module-level singleton gone
Mirror the shape of praisonai._async_bridge.scoped_bridge: resolve the active registry/event-bus from a context variable, with a scoped_* context manager that an embedder wraps around their request/startup.
# api/agent_invoke.py
import contextlib
import contextvars
_current_registry: contextvars.ContextVar[Optional[AgentRegistry]] = (
contextvars.ContextVar("praisonai_agent_registry", default=None)
)
@contextlib.contextmanager
def scoped_agent_registry(registry: Optional[AgentRegistry] = None):
"""Bind ``registry`` (or a fresh one) for the duration of the ``with`` block.
Every free function and every FastAPI dependency resolved inside this
scope sees the bound registry — the single-tenant CLI wraps startup;
multi-tenant embedders wrap each request.
"""
if registry is None:
registry = AgentRegistry()
token = _current_registry.set(registry)
try:
yield registry
finally:
_current_registry.reset(token)
def _active_registry() -> AgentRegistry:
reg = _current_registry.get()
if reg is None:
raise RuntimeError(
"No AgentRegistry bound; call scoped_agent_registry() or pass "
"registry= explicitly."
)
return reg
def _registry_dependency() -> AgentRegistry:
return _active_registry()
def register_agent(agent_id: str, agent: Any,
*, registry: Optional[AgentRegistry] = None) -> None:
(registry or _active_registry()).register(agent_id, agent)
def get_agent(agent_id: str,
*, registry: Optional[AgentRegistry] = None) -> Optional[Any]:
return (registry or _active_registry()).get(agent_id)
Same shape applied to the event bus:
# endpoints/a2u_server.py
_current_event_bus: contextvars.ContextVar[Optional[A2UEventBus]] = (
contextvars.ContextVar("praisonai_a2u_event_bus", default=None)
)
@contextlib.contextmanager
def scoped_event_bus(bus: Optional[A2UEventBus] = None):
if bus is None:
bus = A2UEventBus()
token = _current_event_bus.set(bus)
try:
yield bus
finally:
_current_event_bus.reset(token)
def get_event_bus() -> A2UEventBus:
bus = _current_event_bus.get()
if bus is None:
raise RuntimeError(
"No A2UEventBus bound; call scoped_event_bus() or pass "
"event_bus= explicitly."
)
return bus
Single-tenant callers (CLI praisonai serve, the a2a/a2u sample scripts) wrap their startup in with scoped_agent_registry(): … / with scoped_event_bus(): … once. Multi-tenant hosts (AgentOS, praisonai serve with per-request isolation) wrap each request. Nobody accidentally shares agents or events across tenants, and the free-function surface no longer carries a hidden process-global.
Ranking
Impact and risk of regression, most to least severe:
- Capabilities sync/async duplication (Gap #1) — a drift bug is already live (
moderations.amoderateserves the older model); every future fix to any capability has to be hand-mirrored. ~23 modules affected. Shortest cleanup relative to future maintenance cost. - A2U event bus +
agent_invokefree-function registry singletons (Gap #3) — a quiet cross-tenant bleed in exactly the surfaces (praisonai serve, AgentOS, scheduled tasks calling intoregister_agent/emit) multi-tenant production uses. Was flagged in #5163 and remains unfixed on this branch; the scoped-bridge pattern from PR #5212 is directly reusable here. integrationvsintegrationsnamespace collision (Gap #2) — a confusion / discoverability gap rather than a correctness bug today, but the only cost of fixing it is one deprecation cycle, and leaving it in place means every doc, example, and search result continues to require careful disambiguation.
All three fixes reuse existing seams (_async_bridge, contextvars, Core SDK's praisonaiagents.embedding-style re-export) and preserve the public surface — none widens the API or forces callers to migrate immediately.
- Lingua principale
- Python
- Stelle
- 9.3k
- Fork
- 1.5k
- Merge medio
- 1g 5h
- PR unite (30g)
- 520
Preparare l'ambiente
Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di MervinPraison/PraisonAI
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
MervinPraison/PraisonAI#6710 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
claude
Difficoltà 2/5 1-3 ore Idoneità per principianti 74/100
MervinPraison/PraisonAI#6707 ·
I maintainer di solito rispondono entro 1 giorno
-
bug claude
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 90/100
MervinPraison/PraisonAI#6671 ·
I maintainer di solito rispondono entro 1 giorno
-
Compaction budget regression fixture remains below budget with accurate tokenizationForse di nuovo libera Una pull request per questa issue è stata chiusa senza essere unita. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 62/100
MervinPraison/PraisonAI#5418 · 3 commenti ·
I maintainer di solito rispondono entro 1 giorno
-
bug claude documentation
Difficoltà 2/5 1-3 ore Idoneità per principianti 70/100
MervinPraison/PraisonAI#5341 · 3 commenti ·
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di MervinPraison/PraisonAI
Issue simili
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
I maintainer di solito rispondono entro 2 giorni
-
[Bug]: LANGSMITH_SAMPLING_RATE ignores fractional values (isdigit check), traces 100% of requestsAperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
I maintainer di solito rispondono entro 1 giorno
-
platform/backend tests
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
Significant-Gravitas/AutoGPT#17100 ·
I maintainer di solito rispondono entro 1 giorno
-
bug good first issue
Difficoltà 2/5 1-3 ore Idoneità per principianti 64/100
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 61/100
scverse/infercnvpy#238 ·
I maintainer di solito rispondono entro 1 giorno