windlass.api

api

The Windlass facade — one entry point for the whole framework.

Everything starts here::

from windlass import Windlass

rag = Windlass.rag()                 # a RAG pipeline builder
agent = Windlass.agent()             # an agent builder
llm = Windlass.llm("openai")         # a single component
Windlass.list("chunker")             # what is available

The class is a namespace of static factories, not something you instantiate. Its job is discoverability: one import, and your editor's autocomplete shows you the entire framework.

Windlass

Windlass()

Factory namespace for every Windlass component and builder.

Example

from windlass import Windlass rag = Windlass.rag() rag.ingest_text("Windlass unifies the AI ecosystem behind one API.") 1 "Windlass" in str(rag.ask("What does Windlass do?").contexts[0].content) True

Source code in src\windlass\api.py

def __init__(self) -> None:  # pragma: no cover - guard against misuse
    raise TypeError(
        "Windlass is a namespace of factories, not something to instantiate. "
        "Call Windlass.rag() or Windlass.agent() instead."
    )

rag staticmethod

rag(container: Container | None = None) -> Any

Start building a RAG pipeline.

Parameters:

Name	Type	Description	Default
container	Container | None	Dependency container. Defaults to a child of the process root, so application-wide bindings are inherited.	None

Returns:

Name	Type	Description
A	Any	class:~windlass.rag.builder.RAGBuilder.

Example

from windlass import Windlass rag = (Windlass.rag() ... .chunker("recursive", chunk_size=800) ... .retriever("hybrid") ... .top_k(8)) rag.ingest_text("Vector databases store embeddings.") 1

Source code in src\windlass\api.py

@staticmethod
def rag(container: Container | None = None) -> Any:
    """Start building a RAG pipeline.

    Args:
        container: Dependency container. Defaults to a child of the process
            root, so application-wide bindings are inherited.

    Returns:
        A :class:`~windlass.rag.builder.RAGBuilder`.

    Example:
        >>> from windlass import Windlass
        >>> rag = (Windlass.rag()
        ...        .chunker("recursive", chunk_size=800)
        ...        .retriever("hybrid")
        ...        .top_k(8))
        >>> rag.ingest_text("Vector databases store embeddings.")
        1
    """
    from windlass.rag.builder import RAGBuilder

    return RAGBuilder(container)

agent staticmethod

agent(container: Container | None = None) -> Any

Start building an agent.

Parameters:

Name	Type	Description	Default
container	Container | None	Dependency container.	None

Returns:

Name	Type	Description
An	Any	class:~windlass.agent.builder.AgentBuilder.

Example

from windlass import Windlass agent = Windlass.agent().llm("fake", responses=["Hello!"]) agent.run("Say hello").output 'Hello!'

Source code in src\windlass\api.py

@staticmethod
def agent(container: Container | None = None) -> Any:
    """Start building an agent.

    Args:
        container: Dependency container.

    Returns:
        An :class:`~windlass.agent.builder.AgentBuilder`.

    Example:
        >>> from windlass import Windlass
        >>> agent = Windlass.agent().llm("fake", responses=["Hello!"])
        >>> agent.run("Say hello").output
        'Hello!'
    """
    from windlass.agent.builder import AgentBuilder

    return AgentBuilder(container)

supervisor staticmethod

supervisor(
    agents: dict[str, Any],
    *,
    llm: Any = None,
    descriptions: dict[str, str] | None = None,
    **config: Any
) -> Any

Build a multi-agent supervisor.

Parameters:

Name	Type	Description	Default
agents	dict[str, Any]	Specialists keyed by the name the supervisor will use.	required
llm	Any	The coordinating model. Defaults to the configured provider.	None
descriptions	dict[str, str] | None	What each specialist is for. The supervisor routes on this text, so it is worth writing carefully.	None
**config	Any	Forwarded to :class:~windlass.agent.supervisor.Supervisor.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.agent.supervisor.Supervisor.

Example

from windlass import Windlass boss = Windlass.supervisor( ... {"writer": Windlass.agent().llm("fake", responses=["Drafted."])}, ... llm=Windlass.llm("fake", responses=["Done."]), ... ) boss.broadcast("write something")["writer"].output 'Drafted.'

Source code in src\windlass\api.py

@staticmethod
def supervisor(
    agents: dict[str, Any],
    *,
    llm: Any = None,
    descriptions: dict[str, str] | None = None,
    **config: Any,
) -> Any:
    """Build a multi-agent supervisor.

    Args:
        agents: Specialists keyed by the name the supervisor will use.
        llm: The coordinating model. Defaults to the configured provider.
        descriptions: What each specialist is for. The supervisor routes on
            this text, so it is worth writing carefully.
        **config: Forwarded to :class:`~windlass.agent.supervisor.Supervisor`.

    Returns:
        A :class:`~windlass.agent.supervisor.Supervisor`.

    Example:
        >>> from windlass import Windlass
        >>> boss = Windlass.supervisor(
        ...     {"writer": Windlass.agent().llm("fake", responses=["Drafted."])},
        ...     llm=Windlass.llm("fake", responses=["Done."]),
        ... )
        >>> boss.broadcast("write something")["writer"].output
        'Drafted.'
    """
    from windlass.agent.supervisor import Supervisor

    return Supervisor(
        llm=llm or Windlass.llm(),
        agents={k: (v.build() if hasattr(v, "build") else v) for k, v in agents.items()},
        descriptions=descriptions,
        **config,
    )

llm staticmethod

llm(name: str | None = None, /, **config: Any) -> Any

Construct a language model.

Parameters:

Name	Type	Description	Default
name	str | None	Registry name, or a bare model id like "gpt-4o". Defaults to the configured provider.	None
**config	Any	Provider options.	{}

Returns:

Name	Type	Description
An	Any	class:~windlass.interfaces.llm.LLM.

Raises:

Type	Description
ComponentNotFoundError	For an unknown provider.
MissingDependencyError	When the provider's extra is not installed.

Example

from windlass import Windlass Windlass.llm("fake", responses=["hi"]).complete("x").content 'hi'

Source code in src\windlass\api.py

@staticmethod
def llm(name: str | None = None, /, **config: Any) -> Any:
    """Construct a language model.

    Args:
        name: Registry name, or a bare model id like ``"gpt-4o"``. Defaults
            to the configured provider.
        **config: Provider options.

    Returns:
        An :class:`~windlass.interfaces.llm.LLM`.

    Raises:
        ComponentNotFoundError: For an unknown provider.
        MissingDependencyError: When the provider's extra is not installed.

    Example:
        >>> from windlass import Windlass
        >>> Windlass.llm("fake", responses=["hi"]).complete("x").content
        'hi'
    """
    from windlass.agent.builder import _split_model

    if name:
        provider, model = _split_model(name)
        if model and "model" not in config:
            config["model"] = model
        name = provider
    return REGISTRY.create("llm", name or settings().default_llm, **config)

embedding staticmethod

embedding(name: str | None = None, /, **config: Any) -> Any

Construct an embedding model.

Parameters:

Name	Type	Description	Default
name	str | None	Registry name. Defaults to the configured provider.	None
**config	Any	Provider options.	{}

Returns:

Name	Type	Description
An	Any	class:~windlass.interfaces.embedding.Embedder.

Source code in src\windlass\api.py

@staticmethod
def embedding(name: str | None = None, /, **config: Any) -> Any:
    """Construct an embedding model.

    Args:
        name: Registry name. Defaults to the configured provider.
        **config: Provider options.

    Returns:
        An :class:`~windlass.interfaces.embedding.Embedder`.
    """
    return REGISTRY.create("embedding", name or settings().default_embedding, **config)

vectordb staticmethod

vectordb(name: str | None = None, /, **config: Any) -> Any

Construct a vector store.

Parameters:

Name	Type	Description	Default
name	str | None	Registry name. Defaults to the configured store.	None
**config	Any	Store options.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.interfaces.vectordb.VectorStore.

Source code in src\windlass\api.py

@staticmethod
def vectordb(name: str | None = None, /, **config: Any) -> Any:
    """Construct a vector store.

    Args:
        name: Registry name. Defaults to the configured store.
        **config: Store options.

    Returns:
        A :class:`~windlass.interfaces.vectordb.VectorStore`.
    """
    return REGISTRY.create("vectordb", name or settings().default_vectordb, **config)

chunker staticmethod

chunker(name: str | None = None, /, **config: Any) -> Any

Construct a chunker.

Parameters:

Name	Type	Description	Default
name	str | None	Registry name. Defaults to the configured strategy.	None
**config	Any	Strategy options.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.interfaces.chunker.Chunker.

Example

from windlass import Windlass len(Windlass.chunker("recursive", chunk_size=20).split_text("a " * 40)) > 1 True

Source code in src\windlass\api.py

@staticmethod
def chunker(name: str | None = None, /, **config: Any) -> Any:
    """Construct a chunker.

    Args:
        name: Registry name. Defaults to the configured strategy.
        **config: Strategy options.

    Returns:
        A :class:`~windlass.interfaces.chunker.Chunker`.

    Example:
        >>> from windlass import Windlass
        >>> len(Windlass.chunker("recursive", chunk_size=20).split_text("a " * 40)) > 1
        True
    """
    return REGISTRY.create("chunker", name or settings().default_chunker, **config)

retriever staticmethod

retriever(name: str | None = None, /, **config: Any) -> Any

Construct a retriever.

Parameters:

Name	Type	Description	Default
name	str | None	Registry name. Defaults to the configured strategy.	None
**config	Any	Strategy options. Dense strategies need embedder and vectorstore.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.interfaces.retriever.Retriever.

Source code in src\windlass\api.py

@staticmethod
def retriever(name: str | None = None, /, **config: Any) -> Any:
    """Construct a retriever.

    Args:
        name: Registry name. Defaults to the configured strategy.
        **config: Strategy options. Dense strategies need ``embedder`` and
            ``vectorstore``.

    Returns:
        A :class:`~windlass.interfaces.retriever.Retriever`.
    """
    return REGISTRY.create("retriever", name or settings().default_retriever, **config)

loader staticmethod

loader(name: str | None = None, /, **config: Any) -> Any

Construct a document loader.

Parameters:

Name	Type	Description	Default
name	str | None	Registry name. Omit it for automatic format detection.	None
**config	Any	Loader options.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.interfaces.loader.Loader.

Source code in src\windlass\api.py

@staticmethod
def loader(name: str | None = None, /, **config: Any) -> Any:
    """Construct a document loader.

    Args:
        name: Registry name. Omit it for automatic format detection.
        **config: Loader options.

    Returns:
        A :class:`~windlass.interfaces.loader.Loader`.
    """
    if name is None:
        from windlass.rag.loading import AutoLoader

        return AutoLoader(**config)
    return REGISTRY.create("loader", name, **config)

preprocessor staticmethod

preprocessor(name: str = 'clean', /, **config: Any) -> Any

Construct a preprocessor.

Parameters:

Name	Type	Description	Default
name	str	Registry name.	'clean'
**config	Any	Preprocessor options.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.interfaces.preprocessor.Preprocessor.

Source code in src\windlass\api.py

@staticmethod
def preprocessor(name: str = "clean", /, **config: Any) -> Any:
    """Construct a preprocessor.

    Args:
        name: Registry name.
        **config: Preprocessor options.

    Returns:
        A :class:`~windlass.interfaces.preprocessor.Preprocessor`.
    """
    return REGISTRY.create("preprocessor", name, **config)

memory staticmethod

memory(name: str = 'window', /, **config: Any) -> Any

Construct a memory backend.

Parameters:

Name	Type	Description	Default
name	str	Registry name.	'window'
**config	Any	Memory options.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.interfaces.memory.Memory.

Source code in src\windlass\api.py

@staticmethod
def memory(name: str = "window", /, **config: Any) -> Any:
    """Construct a memory backend.

    Args:
        name: Registry name.
        **config: Memory options.

    Returns:
        A :class:`~windlass.interfaces.memory.Memory`.
    """
    return REGISTRY.create("memory", name, **config)

guardrail staticmethod

guardrail(name: str = 'rules', /, **config: Any) -> Any

Construct a guardrail.

Parameters:

Name	Type	Description	Default
name	str	Registry name.	'rules'
**config	Any	Policy options.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.interfaces.guardrail.Guardrail.

Example

from windlass import Windlass Windlass.guardrail(on_violation="redact").validate("mail a@b.com") 'mail [EMAIL]'

Source code in src\windlass\api.py

@staticmethod
def guardrail(name: str = "rules", /, **config: Any) -> Any:
    """Construct a guardrail.

    Args:
        name: Registry name.
        **config: Policy options.

    Returns:
        A :class:`~windlass.interfaces.guardrail.Guardrail`.

    Example:
        >>> from windlass import Windlass
        >>> Windlass.guardrail(on_violation="redact").validate("mail a@b.com")
        'mail [EMAIL]'
    """
    return REGISTRY.create("guardrail", name, **config)

evaluator staticmethod

evaluator(name: str = 'builtin', /, **config: Any) -> Any

Construct an evaluator.

Parameters:

Name	Type	Description	Default
name	str	Registry name — "builtin", "ragas" or "deepeval".	'builtin'
**config	Any	Evaluator options, including metrics and llm.	{}

Returns:

Name	Type	Description
An	Any	class:~windlass.interfaces.evaluator.Evaluator.

Source code in src\windlass\api.py

@staticmethod
def evaluator(name: str = "builtin", /, **config: Any) -> Any:
    """Construct an evaluator.

    Args:
        name: Registry name — ``"builtin"``, ``"ragas"`` or ``"deepeval"``.
        **config: Evaluator options, including ``metrics`` and ``llm``.

    Returns:
        An :class:`~windlass.interfaces.evaluator.Evaluator`.
    """
    return REGISTRY.create("evaluator", name, **config)

tracer staticmethod

tracer(name: str = 'console', /, **config: Any) -> Any

Construct a tracer.

Parameters:

Name	Type	Description	Default
name	str	Registry name.	'console'
**config	Any	Tracer options.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.interfaces.tracer.Tracer.

Source code in src\windlass\api.py

@staticmethod
def tracer(name: str = "console", /, **config: Any) -> Any:
    """Construct a tracer.

    Args:
        name: Registry name.
        **config: Tracer options.

    Returns:
        A :class:`~windlass.interfaces.tracer.Tracer`.
    """
    return REGISTRY.create("tracer", name, **config)

mcp staticmethod

mcp(name: str = 'fastmcp', /, **config: Any) -> Any

Construct an MCP client.

Parameters:

Name	Type	Description	Default
name	str	Registry name.	'fastmcp'
**config	Any	Transport options.	{}

Returns:

Name	Type	Description
An	Any	class:~windlass.interfaces.mcp.MCPClient.

Source code in src\windlass\api.py

@staticmethod
def mcp(name: str = "fastmcp", /, **config: Any) -> Any:
    """Construct an MCP client.

    Args:
        name: Registry name.
        **config: Transport options.

    Returns:
        An :class:`~windlass.interfaces.mcp.MCPClient`.
    """
    return REGISTRY.create("mcp", name, **config)

checkpointer staticmethod

checkpointer(name: str = 'memory', /, **config: Any) -> Any

Construct a checkpointer.

Parameters:

Name	Type	Description	Default
name	str	Registry name — "memory" or "sqlite".	'memory'
**config	Any	Checkpointer options.	{}

Returns:

Name	Type	Description
A	Any	class:~windlass.agent.checkpoint.Checkpointer.

Source code in src\windlass\api.py

@staticmethod
def checkpointer(name: str = "memory", /, **config: Any) -> Any:
    """Construct a checkpointer.

    Args:
        name: Registry name — ``"memory"`` or ``"sqlite"``.
        **config: Checkpointer options.

    Returns:
        A :class:`~windlass.agent.checkpoint.Checkpointer`.
    """
    return REGISTRY.create("checkpointer", name, **config)

create staticmethod

create(kind: str, name: str, /, **config: Any) -> Any

Construct any registered component, including custom kinds.

Parameters:

Name	Type	Description	Default
kind	str	Component kind.	required
name	str	Registry name.	required
**config	Any	Constructor options.	{}

Returns:

Type	Description
Any	The component.

Source code in src\windlass\api.py

@staticmethod
def create(kind: str, name: str, /, **config: Any) -> Any:
    """Construct any registered component, including custom kinds.

    Args:
        kind: Component kind.
        name: Registry name.
        **config: Constructor options.

    Returns:
        The component.
    """
    return REGISTRY.create(kind, name, **config)

list staticmethod

list(kind: str | None = None) -> Any

List what is registered.

Parameters:

Name	Type	Description	Default
kind	str | None	A component kind, or None for everything grouped by kind.	None

Returns:

Type	Description
Any	Sorted names for one kind, or a {kind: [names]} mapping.

Example

from windlass import Windlass "recursive" in Windlass.list("chunker") True "llm" in Windlass.list() True

Source code in src\windlass\api.py

@staticmethod
def list(kind: str | None = None) -> Any:
    """List what is registered.

    Args:
        kind: A component kind, or ``None`` for everything grouped by kind.

    Returns:
        Sorted names for one kind, or a ``{kind: [names]}`` mapping.

    Example:
        >>> from windlass import Windlass
        >>> "recursive" in Windlass.list("chunker")
        True
        >>> "llm" in Windlass.list()
        True
    """
    if kind is not None:
        return REGISTRY.names(kind)
    return {k: REGISTRY.names(k) for k in REGISTRY.kinds()}

catalog staticmethod

catalog(kind: str | None = None) -> builtins.list[ComponentSpec]

Return full registry entries, including descriptions and extras.

Parameters:

Name	Type	Description	Default
kind	str | None	A component kind, or None for everything.	None

Returns:

Type	Description
list[ComponentSpec]	The matching :class:~windlass.core.registry.ComponentSpec objects.

Source code in src\windlass\api.py

@staticmethod
def catalog(kind: str | None = None) -> builtins.list[ComponentSpec]:
    """Return full registry entries, including descriptions and extras.

    Args:
        kind: A component kind, or ``None`` for everything.

    Returns:
        The matching :class:`~windlass.core.registry.ComponentSpec` objects.
    """
    if kind is not None:
        return REGISTRY.specs(kind)
    return [spec for k in REGISTRY.kinds() for spec in REGISTRY.specs(k)]

kinds staticmethod

kinds() -> builtins.list[str]

Return every component kind Windlass knows about.

Source code in src\windlass\api.py

@staticmethod
def kinds() -> builtins.list[str]:
    """Return every component kind Windlass knows about."""
    return REGISTRY.kinds()

configure staticmethod

configure(**overrides: Any) -> WindlassSettings

Update process-wide settings.

Parameters:

Name	Type	Description	Default
**overrides	Any	Any field of :class:~windlass.core.config.WindlassSettings.	{}

Returns:

Type	Description
WindlassSettings	The new settings.

Example

from windlass import Windlass Windlass.configure(temperature=0.0).temperature 0.0

Source code in src\windlass\api.py

@staticmethod
def configure(**overrides: Any) -> WindlassSettings:
    """Update process-wide settings.

    Args:
        **overrides: Any field of
            :class:`~windlass.core.config.WindlassSettings`.

    Returns:
        The new settings.

    Example:
        >>> from windlass import Windlass
        >>> Windlass.configure(temperature=0.0).temperature
        0.0
    """
    return configure(**overrides)

settings staticmethod

settings() -> WindlassSettings

Return the active settings.

Source code in src\windlass\api.py

@staticmethod
def settings() -> WindlassSettings:
    """Return the active settings."""
    return settings()

container staticmethod

container() -> Container

Return the process-wide root dependency container.

Bindings placed here are inherited by every builder created afterwards, which makes it the right place for application-wide wiring::

Windlass.container().bind_instance("tracer", MyTracer())

Returns:

Type	Description
Container	The root :class:~windlass.core.container.Container.

Source code in src\windlass\api.py

@staticmethod
def container() -> Container:
    """Return the process-wide root dependency container.

    Bindings placed here are inherited by every builder created afterwards,
    which makes it the right place for application-wide wiring::

        Windlass.container().bind_instance("tracer", MyTracer())

    Returns:
        The root :class:`~windlass.core.container.Container`.
    """
    return root_container()

plugins staticmethod

plugins(*, strict: bool = False) -> builtins.list[str]

Discover entry-point plugins.

Runs automatically on first registry lookup; call it explicitly to see what loaded, or with strict=True to surface plugin errors.

Parameters:

Name	Type	Description	Default
strict	bool	Raise on the first plugin that fails.	False

Returns:

Type	Description
list[str]	The names that loaded successfully.

Source code in src\windlass\api.py

@staticmethod
def plugins(*, strict: bool = False) -> builtins.list[str]:
    """Discover entry-point plugins.

    Runs automatically on first registry lookup; call it explicitly to see
    what loaded, or with ``strict=True`` to surface plugin errors.

    Args:
        strict: Raise on the first plugin that fails.

    Returns:
        The names that loaded successfully.
    """
    return REGISTRY.load_plugins(strict=strict)

tools staticmethod

tools(*functions: Any) -> Sequence[Any]

Wrap plain functions as tools.

A convenience for binding several existing functions at once.

Parameters:

Name	Type	Description	Default
*functions	Any	Functions to wrap.	()

Returns:

Type	Description
Sequence[Any]	The resulting tools.

Example

from windlass import Windlass def ping() -> str: ... '''Return pong.''' ... return "pong" [t.name for t in Windlass.tools(ping)]['ping']

Source code in src\windlass\api.py

@staticmethod
def tools(*functions: Any) -> Sequence[Any]:
    """Wrap plain functions as tools.

    A convenience for binding several existing functions at once.

    Args:
        *functions: Functions to wrap.

    Returns:
        The resulting tools.

    Example:
        >>> from windlass import Windlass
        >>> def ping() -> str:
        ...     '''Return pong.'''
        ...     return "pong"
        >>> [t.name for t in Windlass.tools(ping)]
        ['ping']
    """
    from windlass.interfaces.tool import Tool
    from windlass.tools import FunctionTool

    return [f if isinstance(f, Tool) else FunctionTool(f) for f in functions]