agents-builder 1.0.0__py3-none-any.whl

agents_builder/__init__.py

@@ -0,0 +1,95 @@
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from datetime import datetime
+from pathlib import Path
+
+from langchain.tools import BaseTool
+from langgraph.graph.state import CompiledStateGraph
+
+from agents_builder.exceptions import (
+    MCPNotConfiguredError,
+    MCPToolNotFoundError,
+)
+from agents_builder.llm.factory import LLMFactory
+from agents_builder.mixins import FromConfigMixin
+from agents_builder.settings import AgentSettings
+from agents_builder.utils import _cached_mcp_tools, load_class
+
+_logger = logging.getLogger(__name__)
+
+
+class Agent[TConfig: AgentSettings](FromConfigMixin[TConfig], ABC):
+    """
+    Initializes and runs a LangChain agent backed by VLLM and Qdrant embeddings.
+    Minimal version: no exception catching, f-string logs only.
+    """
+
+    def __init__(self, config: TConfig) -> None:
+        self.config = config
+        self._graph: CompiledStateGraph | None = None
+        self.init_components()
+        _logger.info("Agent initialized")
+
+    @property
+    def graph(self) -> CompiledStateGraph:
+        if self._graph is None:
+            _logger.info("Graph not initialized → building graph")
+            self._graph = self.build_graph()
+        return self._graph
+
+    async def load_tool(self, mcp_name: str, key: str) -> BaseTool:
+        # ✅ cache hit
+        if key in self._tools_by_name:
+            return self._tools_by_name[key]
+        async with self._tool_lock:
+            # double-check (important)
+            if key in self._tools_by_name:
+                return self._tools_by_name[key]
+            # 🔥 find the correct MCP
+            mcp = next(
+                (m for m in self.config.mcps if m.name == mcp_name),
+                None,
+            )
+            if mcp is None:
+                raise MCPNotConfiguredError(tool_key=key)
+            # 🔥 load ONLY this MCP
+            tools = await _cached_mcp_tools(
+                mcps_fingerprint=f"{mcp.name}:{mcp.url}",
+                mcps_config=[mcp],  # 👈 only ONE MCP
+            )
+            # cache all tools from this MCP (usually few)
+            for tool in tools:
+                self._tools_by_name[tool.name] = tool
+        if key not in self._tools_by_name:
+            raise MCPToolNotFoundError(
+                tool_key=key,
+                mcp_name=mcp.name,
+                available=list(self._tools_by_name.keys()),
+            )
+        return self._tools_by_name[key]
+
+    def init_components(self) -> None:
+        self.llm_factory: LLMFactory = load_class(self.config.llm_factory.module_path).from_config(
+            self.config.llm_factory
+        )
+        self._tools_by_name: dict[str, BaseTool] = {}
+        self._tool_lock = asyncio.Lock()
+        _logger.info("Agent created")
+
+    def push(self, path: str | None = None) -> None:
+        # Timestamp: YYYYMMDD_HHMMSS
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        # Optional: include agent name / class
+        agent_name = self.__class__.__name__
+        # Build filename
+        filename = f"{agent_name}_graph_{timestamp}.png"
+        # Full path
+        full_path: Path = Path(path) / filename if path else Path(".") / filename
+        # Draw + save
+        png_bytes = self.graph.get_graph().draw_mermaid_png()
+        full_path.write_bytes(png_bytes)
+        _logger.info(f"Graph saved locally at {full_path}")
+
+    @abstractmethod
+    def build_graph(self) -> CompiledStateGraph: ...

agents_builder/constants.py

@@ -0,0 +1,24 @@
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from langchain_core.tools.base import BaseTool
+
+if TYPE_CHECKING:
+    from agents_builder.settings import (
+        AgentSettings,
+        DeletionStrategySettings,
+        FromConfigMixinSettings,
+        LLMSettings,
+    )
+
+TNode = TypeVar("TNode")
+ToolLike = dict[str, Any] | type | Callable | BaseTool
+StructuredOutput = dict[str, Any] | type[Any] | None
+TCFromConfigMixin = TypeVar("TCFromConfigMixin", bound="FromConfigMixinSettings")
+TCAgent = TypeVar("TCAgent", bound="AgentSettings")
+TCDeletionStrategy = TypeVar("TCDeletionStrategy", bound="DeletionStrategySettings")
+
+TCLLM = TypeVar("TCLLM", bound="LLMSettings")
+TCAgentSettings = TypeVar("TCAgentSettings", bound="AgentSettings")
+
+CONFIG_PATH = "/config/config.yaml"

agents_builder/exceptions.py

@@ -0,0 +1,87 @@
+# agents_builder/exceptions.py
+
+
+class AgenticBuilderError(Exception):
+    """Base exception for the package"""
+
+
+# -------------------------
+# MESSAGE / STATE
+# -------------------------
+class MessageError(AgenticBuilderError):
+    pass
+
+
+class NoHumanMessageError(MessageError):
+    pass
+
+
+class InvalidStateError(AgenticBuilderError):
+    pass
+
+
+class MissingStateKeyError(InvalidStateError):
+    def __init__(self, key: str):
+        super().__init__(f"Missing or None key '{key}' in state dict")
+        self.key = key
+
+
+# -------------------------
+# MCP / TOOLS
+# -------------------------
+class MCPError(AgenticBuilderError):
+    pass
+
+
+class MCPNotConfiguredError(MCPError):
+    def __init__(self, tool_key: str):
+        super().__init__(f"No MCP configured for tool '{tool_key}'")
+
+
+class MCPToolNotFoundError(MCPError):
+    def __init__(self, tool_key: str, mcp_name: str, available: list[str]):
+        super().__init__(f"Tool '{tool_key}' not found in MCP '{mcp_name}'. Available: {available}")
+        self.tool_key = tool_key
+        self.mcp_name = mcp_name
+        self.available = available
+
+
+# -------------------------
+# GRAPH / AGENT
+# -------------------------
+class GraphError(AgenticBuilderError):
+    pass
+
+
+# -------------------------
+# PROMPTS
+# -------------------------
+class PromptError(AgenticBuilderError):
+    pass
+
+
+# -------------------------
+# STRATEGIES
+# -------------------------
+class StrategyError(AgenticBuilderError):
+    pass
+
+
+# -------------------------
+# LLM
+# -------------------------
+class LLMError(AgenticBuilderError):
+    pass
+
+
+class InvalidLLMRoleError(LLMError):
+    def __init__(self, role: str, available: list[str]):
+        super().__init__(f"LLM role '{role}' not defined. Available roles: {available}")
+
+
+class InvalidLLMClassError(LLMError):
+    pass
+
+
+class StreamingNotSupportedError(LLMError):
+    pass

agents_builder/langgraph/__init__.py

@@ -0,0 +1,96 @@
+import logging
+from abc import ABC, abstractmethod
+from typing import Any
+
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import AIMessage, BaseMessage, SystemMessage
+from langchain_core.messages.utils import AnyMessage
+from langchain_core.runnables import Runnable
+from langgraph._internal._typing import StateLike
+from langgraph.graph._node import _Node
+
+from agents_builder import Agent
+from agents_builder.mixins import FromConfigMixin
+from agents_builder.settings import DeletionStrategySettings
+
+logger = logging.getLogger(__name__)
+
+
+class Prompt[TState: StateLike](ABC):
+    @classmethod
+    @abstractmethod
+    def format_prompt(cls, state: TState) -> str: ...
+
+    @classmethod
+    def render(cls, state: TState) -> list[BaseMessage]:
+        content = cls.format_prompt(state)
+        return [
+            *state["messages"],  # ty: ignore[not-subscriptable]
+            SystemMessage(content=content),
+        ]
+
+
+class SchemaBasedPrompt[TState: StateLike](Prompt[TState], ABC):
+    @classmethod
+    @abstractmethod
+    def get_schema(cls) -> Any: ...
+
+
+class DeletionStrategy[TConfig: DeletionStrategySettings](FromConfigMixin[TConfig]):
+    def __init__(self, config: TConfig) -> None:
+        self.config = config
+
+    @abstractmethod
+    def _delete(self, messages: list[AnyMessage]) -> list[AnyMessage]: ...
+
+    def delete(self, messages: list[AnyMessage]) -> list[AnyMessage]:
+        before_count = len(messages)
+        logger.debug(f"DeletionStrategy.start | strategy={self.__class__.__name__} | messages_before={before_count}")
+        new_messages = self._delete(messages)
+        after_count = len(new_messages)
+        removed = before_count - after_count
+        logger.info(
+            f"DeletionStrategy.done | strategy={self.__class__.__name__} | removed={removed} | remaining={after_count}"
+        )
+        return new_messages
+
+
+class Node[TState: StateLike](_Node[TState]):
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    async def __call__(self, state: TState) -> Any: ...
+
+
+class RouterNode[TState: StateLike](Node[TState]):
+    def __init__(self, name: str) -> None:
+        super().__init__(name)
+
+
+class ToolBasedNode[TState: StateLike](Node[TState]):
+    def __init__(self, name: str, agent: Agent[Any], mcp_name: str, tool_key: str):
+        super().__init__(name)
+        self.agent = agent
+        self.mcp_name = mcp_name
+        self.tool_key = tool_key
+
+
+class LLMNode[TState: StateLike](Node[TState]):
+    def __init__(
+        self,
+        name: str,
+        model: BaseChatModel,
+        prompt: type[Prompt[TState]],
+        structured_output: dict | type | None,
+    ):
+        super().__init__(name)
+        runnable: Runnable[list[BaseMessage], AIMessage] = model
+
+        if structured_output:
+            runnable = runnable.with_structured_output(structured_output)  # ty: ignore[invalid-assignment]
+        self.runnable = runnable
+        self.prompt = prompt
+
+    async def _ainvoke(self, state: TState) -> AIMessage:
+        messages = self.prompt.render(state)
+        return await self.runnable.ainvoke(messages)

agents_builder/langgraph/nodes.py

@@ -0,0 +1,124 @@
+import json
+from typing import Any
+
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.tools.base import BaseTool
+
+from agents_builder import Agent
+from agents_builder.exceptions import MissingStateKeyError
+from agents_builder.langgraph import (
+    LLMNode,
+    Prompt,
+    RouterNode,
+    SchemaBasedPrompt,
+    ToolBasedNode,
+)
+from agents_builder.langgraph.states import AgentState
+
+
+class GenerateQueryLLMNode(LLMNode[AgentState]):  # ty: ignore[invalid-type-arguments]
+    def __init__(self, name: str, model: BaseChatModel, prompt: type[SchemaBasedPrompt]):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=prompt,
+            structured_output=prompt.get_schema(),
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        query = await self._ainvoke(state)
+        return {"query": query}
+
+
+class SearchDocumentsNode(ToolBasedNode[AgentState]):  # ty: ignore[invalid-type-arguments]
+    def __init__(self, name: str, agent: Agent[Any], mcp_name: str, tool_key: str):
+        super().__init__(name=name, agent=agent, mcp_name=mcp_name, tool_key=tool_key)
+        self.retriever_tool: BaseTool | None = None
+
+    async def __call__(self, state: AgentState) -> Any:
+        if self.retriever_tool is None:
+            self.retriever_tool = await self.agent.load_tool(self.mcp_name, self.tool_key)
+        if state["query"] is None:
+            raise MissingStateKeyError("query")
+        # Call the retriever tool asynchronously
+        tool_result = (await self.retriever_tool.arun({"query": state["query"]["content"]}))[0]
+        # Parse tool output
+        payload = json.loads(tool_result["text"])
+        evidence = payload["retrieval"]["evidence"]
+        # Return state update
+        return {"documents": evidence}
+
+
+class GraderLLMNode(LLMNode[AgentState]):  # ty: ignore[invalid-type-arguments]
+    def __init__(self, name: str, model: BaseChatModel, prompt: type[SchemaBasedPrompt]):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=prompt,
+            structured_output=prompt.get_schema(),
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        return {"is_answerable": (await self._ainvoke(state))}
+
+
+class GenerateAnswerLLMNode(LLMNode[AgentState]):  # ty: ignore[invalid-type-arguments]
+    def __init__(self, name: str, model: BaseChatModel, prompt: type[Prompt]):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=prompt,
+            structured_output=None,
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        response = await self._ainvoke(state)
+        return {"messages": [response]}
+
+
+class AnswerFailureLLMNode(LLMNode[AgentState]):  # ty: ignore[invalid-type-arguments]
+    def __init__(self, name: str, model: BaseChatModel, prompt: type[Prompt]):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=prompt,
+            structured_output=None,
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        response = await self._ainvoke(state)
+        return {"messages": [response]}
+
+
+class IrrelevantQueryLLMNode(LLMNode[AgentState]):  # ty: ignore[invalid-type-arguments]
+    def __init__(self, name: str, model: BaseChatModel, prompt: type[Prompt]):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=prompt,
+            structured_output=None,
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        response = await self._ainvoke(state)
+        return {"messages": [response]}
+
+
+class IsQueryRelevantRouterNode(RouterNode[AgentState]):  # ty: ignore[invalid-type-arguments]
+    def __init__(self, name: str) -> None:
+        super().__init__(name=name)
+
+    async def __call__(self, state: AgentState) -> Any:
+        if state["query"] and state["query"]["content"] != "[NAN]":  # type: ignore[index]
+            return "yes"
+        return "no"
+
+
+class IsDocumentRelevantRouterNode(RouterNode[AgentState]):  # ty: ignore[invalid-type-arguments]
+    def __init__(self, name: str) -> None:
+        super().__init__(name=name)
+
+    async def __call__(self, state: AgentState) -> Any:
+        if state["is_answerable"] is None:
+            raise MissingStateKeyError("is_answerable")
+        return state["is_answerable"]["response"]

agents_builder/langgraph/states.py

@@ -0,0 +1,17 @@
+from typing import Literal, TypedDict
+
+from langgraph.graph import MessagesState
+
+
+class Query(TypedDict):
+    content: str
+
+
+class IsAnswerable(TypedDict):
+    response: Literal["yes", "no"]
+
+
+class AgentState(MessagesState):
+    query: Query | None
+    documents: list[dict[str, str]] | None
+    is_answerable: IsAnswerable | None

agents_builder/llm/__init__.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from typing import Self
+
+from langchain_core.language_models.chat_models import BaseChatModel
+
+from agents_builder.exceptions import StreamingNotSupportedError
+from agents_builder.mixins import FromConfigMixin
+from agents_builder.settings import LLMSettings
+
+
+class LLM[TConfig: LLMSettings](FromConfigMixin[TConfig], ABC):
+    def __init__(self, config: TConfig):
+        super().__init__(config)
+
+    @abstractmethod
+    def to_langchain(self) -> BaseChatModel:
+        raise NotImplementedError()
+
+    def with_streaming(self, streaming: bool = True) -> Self:
+        raise StreamingNotSupportedError("Streaming not supported for this LLM")

agents_builder/llm/factory.py

@@ -0,0 +1,44 @@
+import logging
+from typing import Any
+
+from agents_builder.exceptions import InvalidLLMClassError, InvalidLLMRoleError
+from agents_builder.llm import LLM
+from agents_builder.mixins import FromConfigMixin
+from agents_builder.settings import LLMFactorySettings
+from agents_builder.utils import load_class
+
+_logger = logging.getLogger(__name__)
+
+
+class LLMFactory(FromConfigMixin[LLMFactorySettings]):
+    def __init__(self, config: LLMFactorySettings):
+        super().__init__(config)
+        self._models: dict[str, LLM[Any]] = {}
+        _logger.info(f"LLMFactory initialized with roles: {list(self.config.roles.keys())}")
+
+    def get(self, role: str) -> LLM[Any]:
+        self._validate_role(role)
+        if role in self._models:
+            return self._models[role]
+        model = self._build_model(role)
+        self._models[role] = model
+        _logger.info(f"LLMFactory initialized role '{role}' successfully")
+        return model
+
+    def _validate_role(self, role: str) -> None:
+        if role not in self.config.roles:
+            available = list(self.config.roles.keys())
+            _logger.error(f"Invalid LLM role '{role}'. Available roles: {available}")
+            raise InvalidLLMRoleError(role, available)
+        _logger.debug(f"Validated LLM role '{role}'")
+
+    def _build_model(self, role: str) -> LLM[Any]:
+        role_config = self.config.roles[role]
+        llm_class = load_class(role_config.module_path)
+        if not isinstance(llm_class, type) or not issubclass(llm_class, LLM):
+            _logger.error(f"Loaded class '{role_config.module_path}' is not a subclass of LLM. Got: {llm_class}")
+            raise InvalidLLMClassError(
+                f"Loaded class '{role_config.module_path}' is not a subclass of LLM. Got: {llm_class}"
+            )
+        llm_instance = llm_class.from_config(role_config)
+        return llm_instance

agents_builder/llm/llm.py

@@ -0,0 +1,46 @@
+import logging
+from typing import Self
+
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_ollama import ChatOllama
+from langchain_openrouter import ChatOpenRouter
+
+from agents_builder.llm import LLM
+from agents_builder.settings import OllamaLLMSettings, OpenRouterLLMSettings
+
+_logger = logging.getLogger(__name__)
+
+
+class OllamaLLM(LLM[OllamaLLMSettings]):
+    def __init__(self, config: OllamaLLMSettings):
+        super().__init__(config)
+
+    def to_langchain(self) -> BaseChatModel:
+        model = ChatOllama(model=self.config.model, base_url=self.config.base_url)
+        _logger.info(f"Chat model ready: {self.config.model}")
+        return model
+
+    def with_streaming(self, streaming: bool = True) -> Self:
+        # Ollama streams based on call method (astream), not config
+        return self
+
+
+class OpenRouterLLM(LLM[OpenRouterLLMSettings]):
+    def __init__(self, config: OpenRouterLLMSettings):
+        super().__init__(config)
+        self.streaming = False
+
+    def with_streaming(self, streaming: bool = True) -> Self:
+        self.streaming = streaming
+        return self
+
+    def to_langchain(self) -> BaseChatModel:
+        _logger.info(f"Initializing OpenRouter model: {self.config.model}")
+        model = ChatOpenRouter(
+            model=self.config.model,
+            model_kwargs=self.config.model_kwargs,
+            openrouter_provider=self.config.provider,  # raw dict
+            streaming=self.streaming,
+        )
+        _logger.info(f"OpenRouter Chat model ready: {self.config.model}")
+        return model

agents_builder/mixins.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+from typing import Any, Self, get_args
+
+import yaml
+
+from agents_builder.settings import FromConfigMixinSettings
+
+
+class FromConfigMixin[TConfig: FromConfigMixinSettings]:
+    def __init__(self, config: TConfig) -> None:
+        self.config = config
+
+    @classmethod
+    def get_config_class(cls) -> type[TConfig]:
+        return get_args(cls.__orig_bases__[0])[0]  # type: ignore
+
+    @classmethod
+    def from_config(
+        cls,
+        config: TConfig,
+    ) -> Self:
+        return cls(config)
+
+    @classmethod
+    def from_yaml(
+        cls,
+        path: str,
+        key: str | None = None,
+    ) -> Self:
+        """
+        Load a runtime object from YAML.
+
+        Args:
+            yaml_path: Path to YAML config file
+            settings_cls: Pydantic Settings model to validate config
+            key: Optional top-level YAML key (e.g. "retriever")
+
+        Returns:
+            Instantiated runtime object
+        """
+        yaml_path = Path(path)
+        with yaml_path.open("r") as f:
+            raw: dict[str, Any] = yaml.safe_load(f)
+        if key is not None:
+            raw = raw[key]
+        config = cls.get_config_class().model_validate(raw)
+        return cls.from_config(config)
+
+    @classmethod
+    async def create(cls, config: TConfig) -> Self:
+        return cls.from_config(config)
+
+    @classmethod
+    async def from_yaml_async(
+        cls,
+        path: str,
+        key: str | None = None,
+    ) -> Self:
+        yaml_path = Path(path)
+        with yaml_path.open("r") as f:
+            raw: dict[str, Any] = yaml.safe_load(f)
+
+        if key is not None:
+            raw = raw[key]
+        config_cls: type[TConfig] = cls.get_config_class()
+        config = config_cls.model_validate(raw)
+        return await cls.create(config)
+
+    @classmethod
+    def from_settings(cls) -> Self:
+        """
+        Load runtime object using Pydantic Settings resolution:
+        init > yaml > env > dotenv > secrets
+        """
+        config = cls.get_config_class()()  # ty: ignore[missing-argument]
+        return cls.from_config(config)

agents_builder/settings.py

@@ -0,0 +1,86 @@
+from typing import Annotated, Any, Literal
+
+from pydantic import Field
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    YamlConfigSettingsSource,
+)
+
+from agents_builder.constants import CONFIG_PATH
+
+
+class FromConfigMixinSettings(BaseSettings):
+    module_path: str
+    model_config = SettingsConfigDict(
+        yaml_file=CONFIG_PATH,
+        extra="ignore",
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (
+            init_settings,
+            YamlConfigSettingsSource(settings_cls),
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+        )
+
+
+class MCPServerSettings(BaseSettings):
+    name: str
+    url: str
+
+
+class LLMSettings(FromConfigMixinSettings):
+    model: str
+
+
+class OllamaLLMSettings(LLMSettings):
+    kind: Literal["ollama"]
+    base_url: str
+
+
+class OpenRouterLLMSettings(LLMSettings):
+    kind: Literal["openrouter"]
+    model_kwargs: dict[str, Any]
+    provider: dict[str, Any] | None
+
+
+AnyLLMSettings = Annotated[
+    OllamaLLMSettings | OpenRouterLLMSettings,
+    Field(discriminator="kind"),
+]
+
+
+class LLMFactorySettings(FromConfigMixinSettings):
+    roles: dict[str, AnyLLMSettings]
+
+
+class DeletionStrategySettings(FromConfigMixinSettings):
+    pass
+
+
+class AgentSettings(FromConfigMixinSettings):
+    llm_factory: LLMFactorySettings
+    mcps: list[MCPServerSettings]
+
+
+class TrimDeletionStrategySettings(DeletionStrategySettings):
+    strategy: Literal["first", "last"]
+    max_tokens: int
+    start_on: str
+    end_on: tuple[str, str]
+
+
+class BaseAgentSettings(AgentSettings):
+    pass

agents_builder/utils.py

@@ -0,0 +1,91 @@
+import asyncio
+import importlib
+from typing import Any
+
+from langchain.tools import BaseTool
+from langchain_core.messages import HumanMessage, ToolMessage
+from langchain_core.messages.utils import AnyMessage
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+from agents_builder.exceptions import NoHumanMessageError
+from agents_builder.settings import MCPServerSettings
+
+_mcp_tools_cache: dict[str, list[BaseTool]] = {}
+_mcp_tools_lock = asyncio.Lock()
+
+
+def load_class(path: str) -> Any:
+    module_path, class_name = path.rsplit(".", 1)
+    module = importlib.import_module(module_path)
+    return getattr(module, class_name)
+
+
+def get_latest_human_question(messages: list[AnyMessage]) -> Any:
+    for msg in reversed(messages):
+        if isinstance(msg, HumanMessage):
+            return msg.content
+    raise NoHumanMessageError("No HumanMessage found in messages")
+
+
+def message_content_to_str(content: str | list[str | dict[str, Any]]) -> str:
+    """
+    Normalize LangChain message content to a string.
+    """
+    if isinstance(content, str):
+        return content
+
+    parts: list[str] = []
+    for item in content:
+        if isinstance(item, str):
+            parts.append(item)
+        elif isinstance(item, dict):
+            # Common LC formats: {"text": "..."} or tool payloads
+            if "text" in item and isinstance(item["text"], str):
+                parts.append(item["text"])
+            else:
+                parts.append(str(item))
+    return "\n".join(parts)
+
+
+def extract_retrieved_context(messages: list[AnyMessage]) -> str:
+    """
+    Collect ALL retrieved document contents from the conversation history.
+    """
+    contexts = []
+    for msg in messages:
+        # Tool-based retriever output
+        if isinstance(msg, ToolMessage):
+            contexts.append(message_content_to_str(msg.content))
+    return "\n\n".join(c for c in contexts if c.strip())
+
+
+async def _cached_mcp_tools(
+    mcps_fingerprint: str,
+    mcps_config: list[MCPServerSettings],
+) -> list[BaseTool]:
+    # Fast path (already cached)
+    if mcps_fingerprint in _mcp_tools_cache:
+        return _mcp_tools_cache[mcps_fingerprint]
+
+    async with _mcp_tools_lock:
+        # Double-check inside lock
+        if mcps_fingerprint in _mcp_tools_cache:
+            return _mcp_tools_cache[mcps_fingerprint]
+
+        client = MultiServerMCPClient(
+            {  # ty: ignore[invalid-argument-type]
+                mcp.name: {
+                    "transport": "http",
+                    "url": mcp.url,
+                }
+                for mcp in mcps_config
+            }
+        )
+
+        tools = await client.get_tools()
+        _mcp_tools_cache[mcps_fingerprint] = tools
+        return tools
+
+
+def get_context(documents: list[str]) -> str:
+    return "\n\n".join(documents)

agents_builder-1.0.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: agents-builder
+Version: 1.0.0
+Summary: 
+Author: jalal
+Author-email: jalalkhaldi3@gmail.com
+Requires-Python: >=3.12,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: dotenv (>=0.9.9,<0.10.0)
+Requires-Dist: fastapi (>=0.128.0,<0.129.0)
+Requires-Dist: langchain (>=1.1.0,<2.0.0)
+Requires-Dist: langchain-mcp-adapters (>=0.2.1,<0.3.0)
+Requires-Dist: langchain-ollama (>=1.0.0,<2.0.0)
+Requires-Dist: langchain-openai (>=1.1.5,<2.0.0)
+Requires-Dist: langchain-openrouter (>=0.0.2,<0.0.3)
+Requires-Dist: openinference-instrumentation-langchain (>=0.1.56,<0.2.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: pydantic-settings (>=2.12.0,<3.0.0)
+Description-Content-Type: text/markdown
+
+

agents_builder-1.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+agents_builder/__init__.py,sha256=3GjVUZL-GDNK9bBvBcwQ_qRuZ_uwANxtst4gec8xUlI,3447
+agents_builder/constants.py,sha256=tA4eBkVQHXH3EDOHNjUlsPcwUxFATgclCYNmvUoBRPY,815
+agents_builder/exceptions.py,sha256=YEeu2LVuH2x1Cue0a5hiIJrgo8DdfrbQ7kWx1CQQVck,1869
+agents_builder/langgraph/__init__.py,sha256=EZsIWnvrLmyYnkXOPiftArXPoD_WoYJgdmWt63IKc0s,3153
+agents_builder/langgraph/nodes.py,sha256=alH9CwthJDEHWIzqFfpZfiF3_wZICSmH18u3Xq9cuSc,4414
+agents_builder/langgraph/states.py,sha256=cQHP71RyXrYHLhuQLD-3JE6kTKtemq-N253eddOWqfM,333
+agents_builder/llm/__init__.py,sha256=5IQuMC-hreFv7Br2jPyRA7f3xsbI0laGuh4J9wlvF2M,680
+agents_builder/llm/factory.py,sha256=hi5azO355XcJiZVuqFLTLoxEbE_o_Fi9RJGJZ5q75mY,1874
+agents_builder/llm/llm.py,sha256=rJ-gmGTFl5yqRydEljdC0vK0TRfbOSNct3s4EDPidPI,1579
+agents_builder/mixins.py,sha256=64Bh_bZYQ9gDF88S2xbbaSsdUVWw6LozoV8IOKlDrjE,2099
+agents_builder/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agents_builder/settings.py,sha256=vH5cf2Evn13nUv40U65PutHojhTS8EKaibtPP6Ye_1Q,1960
+agents_builder/utils.py,sha256=R9kwNjnjMnWKeMlYLgvwVJktQrov1vYYRybRtVRgEtU,2800
+agents_builder-1.0.0.dist-info/METADATA,sha256=8erFOzKBJlrHh2Fr6BSado2B1MH7XDOHQgrF1wcLWtk,839
+agents_builder-1.0.0.dist-info/WHEEL,sha256=Vz2fHgx6HFtSwhs8KvkHLqH5Ea4w1_rner5uNVGCeIE,88
+agents_builder-1.0.0.dist-info/RECORD,,

agents_builder-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.3.2
+Root-Is-Purelib: true
+Tag: py3-none-any