from_provider Factory

Reference for the from_provider string-shorthand factory.

from_provider is the canonical entry point for the provider-string API. It implements native-first resolution: when both a native adapter and the LiteLLM universal adapter are installed, the native adapter is preferred. The factory file imports no SDKs at module load — all adapter imports happen inside the function.

Signature

def from_provider(
    model: str,
    *,
    kind: Literal["llm", "embedding"] = "llm",
    prefer_litellm: bool = False,
    **kwargs: Any,
) -> LLMProvider | EmbeddingProvider: ...

Parameters

model

Provider string. Accepted forms:

  • "openai/gpt-4o-mini" — provider-prefixed

  • "anthropic/claude-3-5-sonnet-latest"

  • "bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0"

  • "groq/llama-3.1-8b-instant" (via LiteLLM)

  • "ollama/llama3.2" (via LiteLLM; pass api_base=)

  • "BAAI/bge-small-en-v1.5" (HuggingFace ID, embedding only)

  • "gpt-4o" (bare model name — defaults to openai/ for kind="llm")

kind

"llm" (default) or "embedding". Determines which adapter family is consulted.

prefer_litellm

When True, route through LiteLLM even if a native adapter is available for the provider. Useful for consistency-across-providers testing or LiteLLM-based observability.

**kwargs

Passed verbatim to the adapter constructor. Common keys: api_key, api_base, aws_region, aws_profile, timeout, dimensions (embedding only).

Returns

A configured Provider instance implementing the matching Protocol(s).

Raises

ImportError

No adapter is available for the requested provider. The error message includes an install hint for both the native extra and the universal [litellm] fallback.

ValueError

kind is not "llm" or "embedding".

Resolution algorithm

  1. Parse the provider prefix: provider, _, _ = model.partition("/").

  2. If the model has no prefix:

    1. For kind="llm": default provider is "openai".

    2. For kind="embedding": if the bare name looks like an OpenAI embedding (text-embedding-*), default to openai/; otherwise treat as a HuggingFace ID and default to sentence-transformers.

  3. HuggingFace IDs (org/model where org is not a known provider prefix) always route to sentence-transformers for kind="embedding".

  4. Native-first dispatch: if prefer_litellm=False and the prefix is in the native set, and the corresponding extra is installed, return the native adapter.

    1. LLM native set: {openai, anthropic, bedrock}.

    2. Embedding native set: {openai, sentence-transformers, vertex_ai, bedrock}.

  5. LiteLLM universal fallback: if [litellm] is installed, return LiteLLMProvider / LiteLLMEmbeddingProvider.

  6. Otherwise, raise ImportError with an install hint.

Examples

Provider string → native adapter

from neo4j_agent_memory.llm import from_provider

provider = from_provider("openai/gpt-4o-mini")
# Returns OpenAIProvider when [openai] is installed.

Universal fallback for an unsupported provider

provider = from_provider("groq/llama-3.1-70b-versatile")
# Returns LiteLLMProvider (no native Groq adapter).

Force LiteLLM even when native is available

provider = from_provider("openai/gpt-4o", prefer_litellm=True)
# Returns LiteLLMProvider, ignoring the native adapter.

Local Ollama via LiteLLM

provider = from_provider(
    "ollama/llama3.2",
    api_base="http://localhost:11434",
)

Custom dimensions for an unknown embedder

embedder = from_provider(
    "my-org/private-model",
    kind="embedding",
    dimensions=512,
)

Pass api_key explicitly

provider = from_provider(
    "anthropic/claude-3-5-sonnet-latest",
    api_key="sk-ant-...",
)

Install hints

When no adapter is available, the ImportError message is provider-specific:

No llm adapter available for provider 'anthropic'.

Install one of the following:
  pip install 'neo4j-agent-memory[anthropic]'      # native adapter
  pip install 'neo4j-agent-memory[litellm]'        # universal adapter (recommended)

Debugging which adapter you got

Enable debug logging:

import logging
logging.getLogger("neo4j_agent_memory.llm.factory").setLevel(logging.DEBUG)

from neo4j_agent_memory.llm import from_provider
provider = from_provider("openai/gpt-4o-mini")
# DEBUG: from_provider: routing 'openai/gpt-4o-mini' to native OpenAIProvider

Or just inspect the type:

print(type(provider).__name__)
# OpenAIProvider

Related