agentic-builder 0.1.0__tar.gz

agentic_builder-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: agentic-builder
+Version: 0.1.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: arize-phoenix-client (>=1.28.0,<2.0.0)
+Requires-Dist: arize-phoenix-otel (==0.13.1)
+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
+
+

agentic_builder-0.1.0/agentic_builder/__init__.py

@@ -0,0 +1,32 @@
+import logging
+from typing import Any, Generic
+
+from agentic_builder.agent import Agent
+from agentic_builder.constants import TCAPIRunner
+from agentic_builder.mixins import FromConfigMixin
+from agentic_builder.settings import BaseAPIRunnerSettings
+from agentic_builder.utils import load_class
+
+_logger = logging.getLogger(__name__)
+
+
+class APIRunner(FromConfigMixin[TCAPIRunner], Generic[TCAPIRunner]):
+
+    def __init__(self, config: TCAPIRunner):
+        self.config = config
+        self.agent: Agent[Any]
+
+    @classmethod
+    async def create(cls, config: TCAPIRunner) -> "APIRunner[TCAPIRunner]":
+        self = cls(config)
+        self.agent = await load_class(self.config.agent.module_path).create(self.config.agent)
+        _logger.info("APIRunner initialized")
+        return self
+
+    async def init_agent(self) -> None:
+        self.agent = await load_class(self.config.agent.module_path).create(self.config.agent)
+
+
+class BaseAPIRunner(APIRunner[BaseAPIRunnerSettings]):
+    def __init__(self, config: BaseAPIRunnerSettings):
+        super().__init__(config)

agentic_builder-0.1.0/agentic_builder/agent/__init__.py

@@ -0,0 +1,161 @@
+import logging
+from abc import abstractmethod
+from datetime import datetime
+from pathlib import Path
+from typing import Any, AsyncGenerator, Generic, List, Optional
+
+from agentic_builder.constants import GRAPHS_DIR, TCAgentSettings, TCAPIRunner
+from agentic_builder.llm.factory import LLMFactory
+from agentic_builder.mixins import FromConfigMixin
+from agentic_builder.settings import BaseAPIRunnerSettings
+from agentic_builder.utils import _cached_mcp_tools, load_class
+from langchain.messages import AIMessageChunk
+from langchain.tools import BaseTool
+from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.graph.state import CompiledStateGraph
+from openinference.instrumentation import TracerProvider
+from phoenix.otel import register
+
+_logger = logging.getLogger(__name__)
+
+
+class Agent(FromConfigMixin[TCAgentSettings], Generic[TCAgentSettings]):
+    """
+    Initializes and runs a LangChain agent backed by VLLM and Qdrant embeddings.
+    Minimal version: no exception catching, f-string logs only.
+    """
+
+    _tracer_provider: Optional[TracerProvider] = None
+    _compiled_graph: Optional[CompiledStateGraph] = None
+
+    def __init__(self, config: TCAgentSettings) -> None:
+        self.config = config
+        self.checkpointer = InMemorySaver()
+        self.configurable = {"configurable": {"thread_id": "1"}}
+        _logger.info("Agent initialized")
+
+    @classmethod
+    async def create(cls, config: TCAgentSettings) -> "Agent[TCAgentSettings]":
+        self = cls(config)
+        await self._init_components()
+        _logger.info("Agent initialized")
+        self.push()
+        _logger.info("Graph saved locally")
+        return self
+
+    async def _load_tools(self) -> List[BaseTool]:
+        fingerprint = ",".join(f"{mcp.name}:{mcp.url}" for mcp in self.config.mcps)
+        tools = await _cached_mcp_tools(
+            mcps_fingerprint=fingerprint,
+            mcps_config=self.config.mcps,
+        )
+
+        _logger.info("Loaded %d MCP tools (cached)", len(tools))
+        return tools
+
+    def _load_tracer_provider(self) -> TracerProvider:
+        if self.__class__._tracer_provider is None:
+            _logger.info("Initializing OpenInference tracer provider")
+            self.__class__._tracer_provider = register(
+                endpoint=self.config.phoenix.collector_endpoint,
+                project_name=self.config.phoenix.project_name,
+                auto_instrument=True,
+            )
+        _logger.info("LangChain OpenInference instrumentation enabled")
+        return self.__class__._tracer_provider
+
+    async def _init_components(self) -> None:
+        self.tracer_provider = self._load_tracer_provider()
+        self.tools = await self._load_tools()
+        self.llm_factory: LLMFactory = load_class(self.config.llm_factory.module_path)(self.config.llm_factory)
+        if self.__class__._compiled_graph is None:
+            self.__class__._compiled_graph = self.build_agent()
+        self.agent: CompiledStateGraph = self.__class__._compiled_graph
+        _logger.info(f"Agent created")
+
+    @abstractmethod
+    def build_agent(self) -> CompiledStateGraph:
+        raise NotImplementedError()
+
+    async def arun(self, query: str) -> str:
+        chunks: List[str] = []
+        async for event in self.agent.astream(
+            {"messages": [{"role": "user", "content": query}]},
+            stream_mode="messages",
+        ):
+            msg = event.get("messages", [None])[-1]
+            if isinstance(msg, AIMessageChunk) and msg.text:
+                chunks.append(msg.text)
+        return "".join(chunks)
+
+    async def astream_llm_tokens(self, query: str) -> AsyncGenerator[str, None]:
+        """
+        Stream ONLY LLM tokens (no tool messages, no updates).
+        """
+        _logger.info(f"Streaming agent (LLM-only): {query}")
+
+        async for token, metadata in self.agent.astream(
+            {"messages": [{"role": "user", "content": query}]},
+            config=self.configurable,  # type: ignore[arg-type]
+            stream_mode="messages",
+        ):
+            if isinstance(token, AIMessageChunk) and token.text:
+                yield token.text
+
+    async def render_steps(self, query: str) -> None:
+        async for chunk in self.agent.astream(
+            {
+                "messages": [
+                    {
+                        "role": "user",
+                        "content": query,
+                    }
+                ]
+            },
+            config=self.configurable,  # type: ignore[arg-type]
+        ):
+            for node, update in chunk.items():
+                print("Update from node", node)
+                print(update)
+                if "messages" in update and update["messages"]:
+                    update["messages"][-1].pretty_print()
+
+    def push(self) -> None:
+        # Timestamp: YYYYMMDD_HHMMSS
+        timestamp = datetime.utcnow().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
+        path: Path = GRAPHS_DIR / filename
+
+        # Draw + save
+        png_bytes = self.agent.get_graph().draw_mermaid_png()
+        path.write_bytes(png_bytes)
+        _logger.info(f"Graph saved locally at {path}")
+
+
+class APIRunner(FromConfigMixin[TCAPIRunner], Generic[TCAPIRunner]):
+
+    def __init__(self, config: TCAPIRunner):
+        self.config = config
+        self.agent: Agent[Any]
+
+    @classmethod
+    async def create(cls, config: TCAPIRunner) -> "APIRunner[TCAPIRunner]":
+        self = cls(config)
+        self.agent = await load_class(self.config.agent.module_path).create(self.config.agent)
+        _logger.info("APIRunner initialized")
+        return self
+
+    async def init_agent(self) -> None:
+        self.agent = await load_class(self.config.agent.module_path).create(self.config.agent)
+
+
+class BaseAPIRunner(APIRunner[BaseAPIRunnerSettings]):
+    def __init__(self, config: BaseAPIRunnerSettings):
+        super().__init__(config)

agentic_builder-0.1.0/agentic_builder/agent/base.py

@@ -0,0 +1,18 @@
+import logging
+
+from agentic_builder import Agent
+from agentic_builder.settings import BaseAgentSettings
+from langchain.agents import create_agent
+from langgraph.graph.state import CompiledStateGraph
+
+_logger = logging.getLogger(__name__)
+
+
+class BaseAgent(Agent[BaseAgentSettings]):
+
+    def __init__(self, config: BaseAgentSettings) -> None:
+        super().__init__(config)
+
+    def build_agent(self) -> CompiledStateGraph:
+        model = self.llm_factory.get("fast_latency").to_langchain()
+        return create_agent(model=model, tools=self.tools, checkpointer=self.checkpointer)

agentic_builder-0.1.0/agentic_builder/constants.py

@@ -0,0 +1,35 @@
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Type, TypeVar, Union
+
+from langchain_core.tools.base import BaseTool
+
+if TYPE_CHECKING:
+
+    from agentic_builder.settings import (
+        AgentSettings,
+        APIRunnerSettings,
+        DeletionStrategySettings,
+        FromConfigMixinSettings,
+        LLMSettings,
+    )
+
+CONFIG_PATH = "/config/config.yaml"
+# CONFIG_PATH = "/home/jalal/projects/arxiv-agent/configs/config_agentic_builder.yaml"
+
+agentic_builder_ROOT = Path(__file__).resolve().parent
+GRAPHS_DIR = agentic_builder_ROOT.parent.parent / "graphs"
+GRAPHS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+TCAgentSettings = TypeVar("TCAgentSettings", bound="AgentSettings")
+TCFromConfigMixin = TypeVar("TCFromConfigMixin", bound="FromConfigMixinSettings")
+TCLLM = TypeVar("TCLLM", bound="LLMSettings")
+TCAgent = TypeVar("TCAgent", bound="AgentSettings")
+TCAPIRunner = TypeVar("TCAPIRunner", bound="APIRunnerSettings")
+TCDeletionStrategy = TypeVar("TCDeletionStrategy", bound="DeletionStrategySettings")
+
+TNode = TypeVar("TNode")
+
+
+ToolLike = Union[Dict[str, Any], Type, Callable, BaseTool]
+StructuredOutput = Optional[Union[Dict[str, Any], Type[Any]]]

agentic_builder-0.1.0/agentic_builder/langgraph/__init__.py

@@ -0,0 +1,96 @@
+import logging
+from abc import ABC, abstractmethod
+from typing import Any, Generic, List, Optional, Type, Union
+
+from agentic_builder.constants import TCDeletionStrategy
+from agentic_builder.mixins import FromConfigMixin
+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.graph._node import _Node
+from langgraph.typing import NodeInputT_contra
+
+logger = logging.getLogger(__name__)
+
+
+class Prompt(ABC, Generic[NodeInputT_contra]):
+
+    @classmethod
+    @abstractmethod
+    def _render(cls, state: NodeInputT_contra) -> str:
+        raise NotImplementedError()
+
+    @classmethod
+    def render(cls, state: NodeInputT_contra) -> List[BaseMessage]:
+        content = cls._render(state)
+        return [
+            *state["messages"],  # type: ignore[index]
+            SystemMessage(content=content),
+        ]
+
+
+class SchemaBasedPrompt(Prompt[NodeInputT_contra], Generic[NodeInputT_contra]):
+
+    @classmethod
+    @abstractmethod
+    def get_schema(cls) -> Any:
+        raise NotImplementedError()
+
+
+class DeletionStrategy(FromConfigMixin[TCDeletionStrategy], Generic[TCDeletionStrategy]):
+
+    def __init__(self, config: TCDeletionStrategy) -> None:
+        self.config = config
+
+    def _delete(self, messages: List[AnyMessage]) -> List[AnyMessage]:
+        raise NotImplementedError()
+
+    def delete(self, messages: List[AnyMessage]) -> List[AnyMessage]:
+        before_count = len(messages)
+        logger.debug(
+            f"DeletionStrategy.start | " f"strategy={self.__class__.__name__} | " f"messages_before={before_count}"
+        )
+        new_messages = self._delete(messages)
+        after_count = len(new_messages)
+        removed = before_count - after_count
+        logger.info(
+            f"DeletionStrategy.done | "
+            f"strategy={self.__class__.__name__} | "
+            f"removed={removed} | "
+            f"remaining={after_count}"
+        )
+        return new_messages
+
+
+class Node(_Node[NodeInputT_contra], Generic[NodeInputT_contra]):
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    async def __call__(self, state: NodeInputT_contra) -> Any: ...
+
+
+class RouterNode(Node[NodeInputT_contra], Generic[NodeInputT_contra]):
+    def __init__(self, name: str) -> None:
+        super().__init__(name)
+
+
+class LLMNode(Node[NodeInputT_contra], Generic[NodeInputT_contra]):
+    def __init__(
+        self,
+        name: str,
+        model: BaseChatModel,
+        prompt: Type[Prompt[NodeInputT_contra]],
+        structured_output: Optional[Union[dict, type]],
+    ):
+        super().__init__(name)
+        runnable: Runnable[Any, AIMessage] = model
+
+        if structured_output:
+            runnable = runnable.with_structured_output(structured_output)  # type: ignore[attr-defined]
+        self.runnable = runnable
+        self.prompt = prompt
+
+    async def _ainvoke(self, state: NodeInputT_contra) -> AIMessage:
+        messages = self.prompt.render(state)
+        return await self.runnable.ainvoke(messages)

agentic_builder-0.1.0/agentic_builder/langgraph/nodes.py

@@ -0,0 +1,140 @@
+import json
+from typing import Any
+
+from agentic_builder.langgraph import LLMNode, Node, RouterNode
+from agentic_builder.langgraph.prompts import (
+    AnswerFailurePrompt,
+    GenerateAnswerPrompt,
+    GenerateQuerySchemaBasedPrompt,
+    GraderSchemaBasedPrompt,
+    IrrelevantQueryPrompt,
+)
+from agentic_builder.langgraph.states import AgentState
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.tools.base import BaseTool
+
+
+class GenerateQueryLLMNode(LLMNode[AgentState]):
+    def __init__(
+        self,
+        name: str,
+        model: BaseChatModel,
+    ):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=GenerateQuerySchemaBasedPrompt,
+            structured_output=GenerateQuerySchemaBasedPrompt.get_schema(),
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        query = await self._ainvoke(state)
+        return {"query": query}
+
+
+class SearchDocumentsNode(Node[AgentState]):
+    def __init__(self, name: str, retriever_tool: BaseTool):
+        super().__init__(name=name)
+        self.retriever_tool = retriever_tool
+
+    async def __call__(self, state: AgentState) -> Any:
+        if state["query"] is None:
+            raise ValueError("key 'query' is None in the state dict")
+        # 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]):
+    def __init__(
+        self,
+        name: str,
+        model: BaseChatModel,
+    ):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=GraderSchemaBasedPrompt,
+            structured_output=GraderSchemaBasedPrompt.get_schema(),
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        return {"is_answerable": (await self._ainvoke(state))}
+
+
+class GenerateAnswerLLMNode(LLMNode[AgentState]):
+    def __init__(
+        self,
+        name: str,
+        model: BaseChatModel,
+    ):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=GenerateAnswerPrompt,
+            structured_output=None,
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        response = await self._ainvoke(state)
+        return {"messages": [response]}
+
+
+class AnswerFailureLLMNode(LLMNode[AgentState]):
+    def __init__(
+        self,
+        name: str,
+        model: BaseChatModel,
+    ):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=AnswerFailurePrompt,
+            structured_output=None,
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        response = await self._ainvoke(state)
+        return {"messages": [response]}
+
+
+class IrrelevantQueryLLMNode(LLMNode[AgentState]):
+    def __init__(
+        self,
+        name: str,
+        model: BaseChatModel,
+    ):
+        super().__init__(
+            name=name,
+            model=model,
+            prompt=IrrelevantQueryPrompt,
+            structured_output=None,
+        )
+
+    async def __call__(self, state: AgentState) -> Any:
+        response = await self._ainvoke(state)
+        return {"messages": [response]}
+
+
+class IsQueryRelevantRouterNode(RouterNode[AgentState]):
+    def __init__(self, name: str) -> None:
+        super().__init__(name=name)
+
+    async def __call__(self, state: AgentState) -> Any:
+        if state["query"]["content"] != "[NAN]":  # type: ignore[index]
+            return "yes"
+        return "no"
+
+
+class IsDocumentRelevantRouterNode(RouterNode[AgentState]):
+    def __init__(self, name: str) -> None:
+        super().__init__(name=name)
+
+    async def __call__(self, state: AgentState) -> Any:
+        if state["is_answerable"]:
+            return state["is_answerable"]["response"]
+        raise ValueError("key 'is_answerable' is None in the state dict")