feat: create ragbits-agents package (#569)

Author: micpst

packages/ragbits-agents/CHANGELOG.md

@@ -0,0 +1,6 @@
+# CHANGELOG
+
+## Unreleased
+
+- Add Agent interface (#569)
+- Initial release of the package (#569)

packages/ragbits-agents/README.md

@@ -0,0 +1,23 @@
+# Ragbits Agents
+
+Ragbits Agents contains primitives for building agentic systems.
+
+The package is in the experimental phase, the API may change in the future.
+
+## Installation
+
+To install the Ragbits Agents package, run:
+
+```sh
+pip install ragbits-agents
+```
+
+<!--
+TODO: Add a minimalistic example inspired by the Quickstart chapter on Ragbits Evaluate once it is ready.
+-->
+
+<!--
+TODO:
+* Add link to the Quickstart chapter on Ragbits Evaluate once it is ready.
+* Add link to API Reference once classes from the Evaluate package are added to the API Reference.
+-->

packages/ragbits-agents/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "ragbits-agents"
+version = "0.18.0"
+description = "Building blocks for rapid development of GenAI applications"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "deepsense.ai", email = "ragbits@deepsense.ai"}
+]
+keywords = [
+    "Retrieval Augmented Generation",
+    "RAG",
+    "Large Language Models",
+    "LLMs",
+    "Generative AI",
+    "GenAI",
+    "Agents",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["ragbits-core==0.18.0"]
+
+[project.urls]
+"Homepage" = "https://github.com/deepsense-ai/ragbits"
+"Bug Reports" = "https://github.com/deepsense-ai/ragbits/issues"
+"Documentation" = "https://ragbits.deepsense.ai/"
+"Source" = "https://github.com/deepsense-ai/ragbits"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ragbits"]

packages/ragbits-agents/src/ragbits/agents/__init__.py

@@ -0,0 +1,4 @@
+from ragbits.agents._main import Agent, AgentOptions
+from ragbits.agents.types import QuestionAnswerAgent, QuestionAnswerPromptInput, QuestionAnswerPromptOutput
+
+__all__ = ["Agent", "AgentOptions", "QuestionAnswerAgent", "QuestionAnswerPromptInput", "QuestionAnswerPromptOutput"]

packages/ragbits-agents/src/ragbits/agents/_main.py

@@ -0,0 +1,102 @@
+from dataclasses import dataclass
+from types import ModuleType
+from typing import Any, ClassVar, Generic, cast, overload
+
+from ragbits import agents
+from ragbits.core.llms.base import LLM, LLMClientOptionsT
+from ragbits.core.options import Options
+from ragbits.core.prompt.prompt import Prompt, PromptInputT, PromptOutputT
+from ragbits.core.types import NOT_GIVEN, NotGiven
+from ragbits.core.utils.config_handling import ConfigurableComponent
+
+
+@dataclass
+class AgentResult(Generic[PromptOutputT]):
+    """
+    Result of the agent run.
+    """
+
+    content: PromptOutputT
+    """The output content of the LLM."""
+    metadata: dict
+    """The additional data returned by the LLM."""
+
+
+class AgentOptions(Options, Generic[LLMClientOptionsT]):
+    """
+    Options for the agent run.
+    """
+
+    llm_options: LLMClientOptionsT | None | NotGiven = NOT_GIVEN
+    """The options for the LLM."""
+
+
+class Agent(
+    ConfigurableComponent[AgentOptions[LLMClientOptionsT]], Generic[LLMClientOptionsT, PromptInputT, PromptOutputT]
+):
+    """
+    Agent class that orchestrates the LLM and the prompt.
+
+    Current implementation is highly experimental, and the API is subject to change.
+    """
+
+    options_cls: type[AgentOptions] = AgentOptions
+    default_module: ClassVar[ModuleType | None] = agents
+    configuration_key: ClassVar[str] = "agent"
+
+    def __init__(
+        self,
+        llm: LLM[LLMClientOptionsT],
+        prompt: type[Prompt[PromptInputT, PromptOutputT]],
+        *,
+        default_options: AgentOptions[LLMClientOptionsT] | None = None,
+    ) -> None:
+        """
+        Initialize the agent instance.
+
+        Args:
+            llm: The LLM to use.
+            prompt: The prompt to use.
+            default_options: The default options for the agent run.
+        """
+        super().__init__(default_options)
+        self.llm = llm
+        self.prompt = prompt
+
+    @overload
+    async def run(
+        self: "Agent[LLMClientOptionsT, PromptInputT, PromptOutputT]",
+        input: PromptInputT,
+        options: AgentOptions[LLMClientOptionsT] | None = None,
+    ) -> AgentResult[PromptOutputT]: ...
+
+    @overload
+    async def run(
+        self: "Agent[LLMClientOptionsT, None, PromptOutputT]",
+        options: AgentOptions[LLMClientOptionsT] | None = None,
+    ) -> AgentResult[PromptOutputT]: ...
+
+    async def run(self, *args: Any, **kwargs: Any) -> AgentResult[PromptOutputT]:  # noqa: D417
+        """
+        Run the agent. The method is experimental, inputs and outputs may change in the future.
+
+        Args:
+            input: The input for the agent run.
+            options: The options for the agent run.
+
+        Returns:
+            The result of the agent run.
+        """
+        input = cast(PromptInputT, args[0] if args else kwargs.get("input"))
+        options = args[1] if len(args) > 1 else kwargs.get("options")
+
+        merged_options = (self.default_options | options) if options else self.default_options
+        llm_options = merged_options.llm_options or None
+
+        prompt = self.prompt(input)
+        response = await self.llm.generate_with_metadata(prompt, options=llm_options)
+
+        return AgentResult(
+            content=response.content,
+            metadata=response.metadata,
+        )

packages/ragbits-agents/src/ragbits/agents/py.typed

@@ -0,0 +1,31 @@
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from ragbits.agents._main import Agent
+from ragbits.core.llms.base import LLMClientOptionsT
+
+QuestionAnswerPromptInputT = TypeVar("QuestionAnswerPromptInputT", bound="QuestionAnswerPromptInput")
+QuestionAnswerPromptOutputT = TypeVar("QuestionAnswerPromptOutputT", bound="QuestionAnswerPromptOutput | str")
+
+QuestionAnswerAgent = Agent[LLMClientOptionsT, QuestionAnswerPromptInputT, QuestionAnswerPromptOutputT]
+
+
+class QuestionAnswerPromptInput(BaseModel):
+    """
+    Input for the question answer agent.
+    """
+
+    question: str
+    """The question to answer."""
+    context: Any | None = None
+    """The context to answer the question."""
+
+
+class QuestionAnswerPromptOutput(BaseModel):
+    """
+    Output for the question answer agent.
+    """
+
+    answer: str
+    """The answer to the question."""

packages/ragbits-agents/src/ragbits/agents/types.py

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- rename typevars InputT and OutputT to PromptInputT and PromptOutputT (#569)
+
 ## 0.18.0 (2025-05-22)
 
 - Allow to limit VectorStore results by metadata (#564)

packages/ragbits-core/CHANGELOG.md

@@ -12,7 +12,7 @@
     BasePrompt,
     BasePromptWithParser,
     ChatFormat,
-    OutputT,
+    PromptOutputT,
     SimplePrompt,
 )
 from ragbits.core.utils.config_handling import ConfigurableComponent
@@ -30,12 +30,12 @@ class LLMType(enum.Enum):
     STRUCTURED_OUTPUT = "structured_output"
 
 
-class LLMResponseWithMetadata(BaseModel, Generic[OutputT]):
+class LLMResponseWithMetadata(BaseModel, Generic[PromptOutputT]):
     """
     A schema of output with metadata
     """
 
-    content: OutputT
+    content: PromptOutputT
     metadata: dict
 
 
@@ -124,18 +124,18 @@ async def generate_raw(
     @overload
     async def generate(
         self,
-        prompt: BasePromptWithParser[OutputT],
+        prompt: BasePromptWithParser[PromptOutputT],
         *,
         options: LLMClientOptionsT | None = None,
-    ) -> OutputT: ...
+    ) -> PromptOutputT: ...
 
     @overload
     async def generate(
         self,
         prompt: BasePrompt,
         *,
         options: LLMClientOptionsT | None = None,
-    ) -> OutputT: ...
+    ) -> PromptOutputT: ...
 
     @overload
     async def generate(
@@ -158,7 +158,7 @@ async def generate(
         prompt: BasePrompt | str | ChatFormat,
         *,
         options: LLMClientOptionsT | None = None,
-    ) -> OutputT:
+    ) -> PromptOutputT:
         """
         Prepares and sends a prompt to the LLM and returns the parsed response.
 
@@ -177,7 +177,7 @@ async def generate(
             if isinstance(prompt, BasePromptWithParser):
                 response = await prompt.parse_response(raw_response["response"])
             else:
-                response = cast(OutputT, raw_response["response"])
+                response = cast(PromptOutputT, raw_response["response"])
             raw_response["response"] = response
             outputs.response = raw_response
 
@@ -186,26 +186,26 @@ async def generate(
     @overload
     async def generate_with_metadata(
         self,
-        prompt: BasePromptWithParser[OutputT],
+        prompt: BasePromptWithParser[PromptOutputT],
         *,
         options: LLMClientOptionsT | None = None,
-    ) -> LLMResponseWithMetadata[OutputT]: ...
+    ) -> LLMResponseWithMetadata[PromptOutputT]: ...
 
     @overload
     async def generate_with_metadata(
         self,
         prompt: BasePrompt,
         *,
         options: LLMClientOptionsT | None = None,
-    ) -> LLMResponseWithMetadata[OutputT]: ...
+    ) -> LLMResponseWithMetadata[PromptOutputT]: ...
 
     @overload
     async def generate_with_metadata(
         self,
         prompt: str,
         *,
         options: LLMClientOptionsT | None = None,
-    ) -> LLMResponseWithMetadata[OutputT]: ...
+    ) -> LLMResponseWithMetadata[PromptOutputT]: ...
 
     @overload
     @overload
@@ -214,14 +214,14 @@ async def generate_with_metadata(
         prompt: ChatFormat,
         *,
         options: LLMClientOptionsT | None = None,
-    ) -> LLMResponseWithMetadata[OutputT]: ...
+    ) -> LLMResponseWithMetadata[PromptOutputT]: ...
 
     async def generate_with_metadata(
         self,
         prompt: BasePrompt | str | ChatFormat,
         *,
         options: LLMClientOptionsT | None = None,
-    ) -> LLMResponseWithMetadata[OutputT]:
+    ) -> LLMResponseWithMetadata[PromptOutputT]:
         """
         Prepares and sends a prompt to the LLM and returns response parsed to the
         output type of the prompt (if available).

packages/ragbits-core/src/ragbits/core/llms/base.py

@@ -5,7 +5,7 @@
 from typing_extensions import TypeVar
 
 ChatFormat = list[dict[str, Any]]
-OutputT = TypeVar("OutputT", default=str)
+PromptOutputT = TypeVar("PromptOutputT", default=str)
 
 
 class BasePrompt(metaclass=ABCMeta):
@@ -47,22 +47,22 @@ def list_images(self) -> list[str]:  # noqa: PLR6301
         return []
 
 
-class BasePromptWithParser(Generic[OutputT], BasePrompt, metaclass=ABCMeta):
+class BasePromptWithParser(Generic[PromptOutputT], BasePrompt, metaclass=ABCMeta):
     """
     Base class for prompts that know how to parse the output from the LLM to their specific
     output type.
     """
 
     @abstractmethod
-    async def parse_response(self, response: str) -> OutputT:
+    async def parse_response(self, response: str) -> PromptOutputT:
         """
         Parse the response from the LLM to the desired output type.
 
         Args:
             response (str): The response from the LLM.
 
         Returns:
-            OutputT: The parsed response.
+            PromptOutputT: The parsed response.
 
         Raises:
             ResponseParsingError: If the response cannot be parsed.