Plugin Precedence

Built-in names always win over entry-point plugins — one rule, enforced in the base PluginRegistry for every registry

Every PraisonAI registry follows one rule: a built-in name always wins over an entry-point plugin — whichever entry-point group the plugin publishes under, canonical or a deprecated legacy spelling. Publishing a pip package with an entry point named openai, docker, or aws has no effect — the built-in resolves. Runtime register(...) is the only deliberate override path.

from praisonai.llm.registry import get_default_llm_registry

# A pip plugin named "openai" is silently dropped (DEBUG log).
# The supported override is an explicit, in-process register(...) call:
def _my_openai():
    from my_pkg import MyOpenAI
    return MyOpenAI

get_default_llm_registry().register("openai", _my_openai, override=True)

The plugin author does not accidentally hijack a built-in through a pyproject.toml; overriding a built-in is always a deliberate, in-process decision.

Quick Start

1. Pick a name that does not collide

   Names are matched case-insensitively against the built-ins of the registry you target. openai, OpenAI, and OPENAI are the same key — pick something novel.

   # pyproject.toml — additive plugin, resolves fine
   [project.entry-points."praisonai.llm_providers"]
   acme-llm = "acme_llm:AcmeProvider"

2. Override a built-in deliberately (runtime only)

   The one supported way to replace a built-in is an in-process register(...) call:

   from praisonai.llm.registry import get_default_llm_registry
   
   def _my_openai():
       from acme_llm import PatchedOpenAI
       return PatchedOpenAI
   
   get_default_llm_registry().register("openai", _my_openai, override=True)

3. Confirm what resolved

   Turn on DEBUG logging to see the collision line noting that a shipped built-in kept its name.

   LOGLEVEL=DEBUG praisonai run "hello"

How It Works

Since PraisonAI PR #4176 the guard lives in the base PluginRegistry, so every registry that subclasses it inherits the behaviour. It is enforced once, not re-asserted per registry.

Some registries also honour deprecated (legacy) entry-point group spellings for backward compatibility. Legacy discovery runs first (so the canonical spelling wins on a clash), and since PraisonAI PR #4185 it applies the same built-in check — you cannot resurrect the old shadowing behaviour by falling back to a deprecated group.

Standalone installs of praisonai-sandbox and praisonai-deploy carry a vendored fallback copy of PluginRegistry that runs when praisonai-code isn’t importable (pip install praisonai-sandbox on its own). Since PraisonAI PR #4184 both vendored copies enforce the same built-in check — an entry point whose name (case-insensitive) matches a built-in is skipped on that path too, so the guarantee holds in every install shape. Prior to PR #4184 a standalone praisonai-sandbox install still let a pip plugin replace docker, and praisonai-deploy let one replace aws.

The same rule runs on the vendored fallback path used by standalone praisonai-sandbox / praisonai-deploy installs:

Every Registry Is Guarded

The two groups that matter most decide where user code executes: praisonai.sandbox and praisonai.managed_backends. A pip-installed package cannot silently take over docker — whether via the canonical base class (PR #4176), the legacy group spelling (PR #4185), or the vendored fallback copy that runs when praisonai-sandbox / praisonai-deploy is installed standalone (PR #4184).

Compatibility

Best Practices

Related