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

Aperta
#5,743 4 commenti 0 reazioni 0 assegnatari Vedi su GitHub

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
Tipo di issue
Refactoring
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
python
Ambito
backend

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

bug claude documentation origin/outsider

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 metadata field 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 by capabilities/__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 moderate through the sync entry point and amoderate through 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_bridge runs 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 modules
  • src/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-line sys.modules-swap shim for the PraisonAIUI host bootstrap (host_app, gateway_host, context_files, pages). All files delegate to praisonai_bot.integration.*. From integration/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 group praisonai.integrations. From integrations/__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 integration vs integrations tells a caller which one hosts UI bootstrap and which one hosts external CLI tool plugins. A missed s resolves to a shim module that does sys.modules[__name__] = <something totally different>; a user who typos either direction sees "AttributeError: module praisonai.integrations has no attribute host_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 to praisonai_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.py
  • src/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 contextvars seam 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:

  1. Capabilities sync/async duplication (Gap #1) — a drift bug is already live (moderations.amoderate serves the older model); every future fix to any capability has to be hand-mirrored. ~23 modules affected. Shortest cleanup relative to future maintenance cost.
  2. A2U event bus + agent_invoke free-function registry singletons (Gap #3) — a quiet cross-tenant bleed in exactly the surfaces (praisonai serve, AgentOS, scheduled tasks calling into register_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.
  3. integration vs integrations namespace 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

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di MervinPraison/PraisonAI

Tutte le issue di MervinPraison/PraisonAI

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.