[Feature] Add core and base modules (#1)

* add core and base modules

* add conftest and test init agent

Author: nerdai

pyproject.toml

@@ -29,5 +29,7 @@ authors = [
 ]
 requires-python = ">=3.10"
 dependencies = [
-  "mcp[cli]>=1.9.4"
+  "asyncio>=3.4.3",
+  "mcp[cli]>=1.9.4",
+  "pydantic>=2.11.7"
 ]

pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+asyncio_mode=auto

src/llm_agents_from_scratch/base/__init__.py

@@ -0,0 +1,31 @@
+"""Base LLM"""
+
+from abc import ABC, abstractmethod
+
+from llm_agents_from_scratch.data_structures import ChatMessage, CompleteResult
+
+
+class BaseLLM(ABC):
+    """Base LLM Class."""
+
+    @abstractmethod
+    async def complete(self, prompt: str) -> CompleteResult:
+        """Text Complete.
+
+        Args:
+            prompt (str): The prompt the LLM should use as input.
+
+        Returns:
+            str: The completion of the prompt.
+        """
+
+    @abstractmethod
+    async def chat(self, chat_messages: list[ChatMessage]) -> ChatMessage:
+        """Chat interface.
+
+        Args:
+            chat_messages (list[ChatMessage]): chat history.
+
+        Returns:
+            ChatMessage: The response of the LLM structured as a `ChatMessage`.
+        """

src/llm_agents_from_scratch/base/llm.py

@@ -0,0 +1,5 @@
+"""Base Tool"""
+
+
+class BaseTool:
+    pass

src/llm_agents_from_scratch/base/tool.py

@@ -0,0 +1,3 @@
+from .agent import LLMAgent
+
+__all__ = ["LLMAgent"]

src/llm_agents_from_scratch/core/__init__.py

@@ -0,0 +1,25 @@
+"""Agent Module."""
+
+from typing_extensions import Self
+
+from llm_agents_from_scratch.base.llm import BaseLLM
+from llm_agents_from_scratch.base.tool import BaseTool
+
+
+class LLMAgent:
+    """A simple LLM Agent Class."""
+
+    def __init__(self, llm: BaseLLM, tools: list[BaseTool] = []):
+        self.llm = llm
+        self.tools = tools
+
+    def add_tool(self, tool: BaseTool) -> Self:
+        """Add a tool to the agents tool set.
+
+        NOTE: Supports fluent style for convenience.
+
+        Args:
+            tool (BaseTool): The tool to equip the LLM agent.
+        """
+        self.tools = self.tools + [tool]
+        return self

src/llm_agents_from_scratch/core/agent.py

@@ -0,0 +1,8 @@
+from .llm import ChatMessage, ChatRole, CompleteResult
+
+__all__ = [
+    # llm
+    "ChatRole",
+    "ChatMessage",
+    "CompleteResult",
+]

src/llm_agents_from_scratch/data_structures/__init__.py

@@ -0,0 +1,23 @@
+"""Data Structures for LLMs"""
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ChatRole(str, Enum):
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+    TOOL_CALL = "tool_call"
+
+
+class ChatMessage(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    role: ChatRole
+    content: str
+
+
+class CompleteResult(BaseModel):
+    response: str
+    full_response: str

src/llm_agents_from_scratch/data_structures/llm.py

@@ -0,0 +1,20 @@
+import pytest
+
+from llm_agents_from_scratch.base.llm import BaseLLM
+from llm_agents_from_scratch.data_structures import ChatMessage, CompleteResult
+
+
+class MockBaseLLM(BaseLLM):
+    async def complete(self, prompt: str) -> CompleteResult:
+        result = "mock complete"
+        return CompleteResult(
+            response=result, full_response=f"{prompt} {result}"
+        )
+
+    async def chat(self, chat_messages: list[ChatMessage]) -> ChatMessage:
+        return ChatMessage(role="assistant", content="mock chat response")
+
+
+@pytest.fixture()
+def mock_llm() -> BaseLLM:
+    return MockBaseLLM()