llm-agent-base 0.1.0__py3-none-any.whl

llm_agent_base/__init__.py

@@ -0,0 +1,15 @@
+from .agent_base import AgentBase
+from .agent_pipeline_base import AgentPipelineBase
+from .knowledge_base import DocumentChunk, KnowledgeBase
+from .llm_connection_config import LLMConnectionConfig
+from .tool_calling import build_tool_schema, execute_tool_loop
+
+__all__ = [
+    "AgentBase",
+    "AgentPipelineBase",
+    "DocumentChunk",
+    "KnowledgeBase",
+    "LLMConnectionConfig",
+    "build_tool_schema",
+    "execute_tool_loop",
+]

llm_agent_base/agent_base.py

@@ -0,0 +1,70 @@
+from typing import Callable, Optional
+
+from .knowledge_base import DocumentChunk, KnowledgeBase
+from .llm_connection_config import LLMConnectionConfig
+from .tool_calling import build_tool_schema, execute_tool_loop
+
+
+class AgentBase:
+    def __init__(
+        self,
+        system_prompt: str,
+        llm_config: LLMConnectionConfig,
+        knowledge_folder_path: Optional[str] = None,
+        knowledge_index_dir: str = ".kb_index",
+        knowledge_top_k: int = 5,
+        debug: bool = False,
+    ):
+        self.system_prompt = system_prompt
+        self.llm_config = llm_config
+        self.knowledge_top_k = knowledge_top_k
+        self.debug = debug
+        self._client = llm_config.build_client()
+        self._kb: Optional[KnowledgeBase] = None
+        self._tools: dict[str, tuple[Callable, dict]] = {}
+
+        if knowledge_folder_path:
+            self._kb = KnowledgeBase(
+                folder_path=knowledge_folder_path,
+                llm_config=llm_config,
+                index_dir=knowledge_index_dir,
+            )
+
+    def register_tool(self, fn: Callable) -> Callable:
+        """Register a Python function as a callable tool. Can be used as a decorator."""
+        self._tools[fn.__name__] = (fn, build_tool_schema(fn))
+        return fn
+
+    def ingest_knowledge(self, save: bool = True) -> int:
+        if self._kb is None:
+            return 0
+        count = self._kb.ingest()
+        if save:
+            self._kb.save()
+        return count
+
+    def load_knowledge(self):
+        if self._kb is not None:
+            self._kb.load()
+
+    def retrieve_knowledge(self, query: str) -> list[DocumentChunk]:
+        if self._kb is None:
+            return []
+        if self.debug:
+            print("[debug] Retrieving knowledge")
+        return self._kb.retrieve(query, top_k=self.knowledge_top_k)
+
+    def run(self, prompt: str) -> str:
+        chunks = self.retrieve_knowledge(prompt)
+
+        system = self.system_prompt
+        if chunks:
+            context = "\n\n".join(f"[{c.source}]\n{c.text}" for c in chunks)
+            system = f"{system}\n\n<context>\n{context}\n</context>"
+
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": prompt},
+        ]
+
+        return execute_tool_loop(self._client, self.llm_config.model, messages, self._tools, debug=self.debug)

llm_agent_base/agent_pipeline_base.py

@@ -0,0 +1,12 @@
+from .agent_base import AgentBase
+
+
+class AgentPipelineBase:
+    def __init__(self, agents: list[AgentBase]):
+        self._agents = agents
+
+    def run(self, prompt: str) -> str:
+        result = prompt
+        for agent in self._agents:
+            result = agent.run(result)
+        return result

llm_agent_base/knowledge_base.py

@@ -0,0 +1,145 @@
+import json
+import pickle
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+import faiss
+
+from .llm_connection_config import LLMConnectionConfig
+
+
+@dataclass
+class DocumentChunk:
+    text: str
+    source: str
+    chunk_index: int
+    metadata: dict = field(default_factory=dict)
+
+
+class KnowledgeBase:
+    SUPPORTED_EXTENSIONS = {".txt", ".md", ".json", ".pdf"}
+
+    def __init__(
+        self,
+        folder_path: str,
+        llm_config: LLMConnectionConfig,
+        index_dir: str = ".kb_index",
+        chunk_size: int = 1000,
+        chunk_overlap: int = 100,
+    ):
+        self.folder_path = Path(folder_path)
+        self.index_dir = Path(index_dir)
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.embedding_model = llm_config.embedding_model
+        self._client = llm_config.build_client()
+
+        self._chunks: list[DocumentChunk] = []
+        self._index: Optional[faiss.IndexFlatIP] = None
+        self._dim: Optional[int] = None
+
+    # ------------------------------------------------------------------ #
+    # Public API                                                           #
+    # ------------------------------------------------------------------ #
+
+    def ingest(self) -> int:
+        """Parse all files in folder_path, chunk, embed, and build the index."""
+        self._chunks = []
+        vectors = []
+
+        for path in sorted(self.folder_path.rglob("*")):
+            if path.suffix.lower() not in self.SUPPORTED_EXTENSIONS:
+                continue
+            text = self._parse_file(path)
+            if not text:
+                continue
+            for i, chunk_text in enumerate(self._chunk_text(text)):
+                chunk = DocumentChunk(
+                    text=chunk_text,
+                    source=str(path.relative_to(self.folder_path)),
+                    chunk_index=i,
+                )
+                self._chunks.append(chunk)
+                vectors.append(self._embed(chunk_text))
+
+        if not vectors:
+            return 0
+
+        matrix = np.array(vectors, dtype="float32")
+        self._dim = matrix.shape[1]
+        faiss.normalize_L2(matrix)
+        self._index = faiss.IndexFlatIP(self._dim)
+        self._index.add(matrix)
+        return len(self._chunks)
+
+    def save(self):
+        """Persist the FAISS index and chunk catalog to disk."""
+        self.index_dir.mkdir(parents=True, exist_ok=True)
+        faiss.write_index(self._index, str(self.index_dir / "index.faiss"))
+        with open(self.index_dir / "catalog.pkl", "wb") as f:
+            pickle.dump({"chunks": self._chunks, "dim": self._dim}, f)
+
+    def load(self):
+        """Restore a previously saved index and catalog from disk."""
+        index_path = self.index_dir / "index.faiss"
+        catalog_path = self.index_dir / "catalog.pkl"
+        if not index_path.exists() or not catalog_path.exists():
+            raise FileNotFoundError(f"No saved index found in {self.index_dir}")
+        self._index = faiss.read_index(str(index_path))
+        with open(catalog_path, "rb") as f:
+            data = pickle.load(f)
+        self._chunks = data["chunks"]
+        self._dim = data["dim"]
+
+    def retrieve(self, query: str, top_k: int = 5) -> list[DocumentChunk]:
+        """Return the top_k most relevant chunks for the given query."""
+        if self._index is None or self._index.ntotal == 0:
+            return []
+        vec = np.array([self._embed(query)], dtype="float32")
+        faiss.normalize_L2(vec)
+        _scores, indices = self._index.search(vec, min(top_k, self._index.ntotal))
+        return [self._chunks[i] for i in indices[0] if i >= 0]
+
+    # ------------------------------------------------------------------ #
+    # Private helpers                                                      #
+    # ------------------------------------------------------------------ #
+
+    def _parse_file(self, path: Path) -> str:
+        ext = path.suffix.lower()
+        if ext == ".pdf":
+            return self._parse_pdf(path)
+        if ext == ".json":
+            return self._parse_json(path)
+        return path.read_text(encoding="utf-8", errors="ignore")
+
+    @staticmethod
+    def _parse_pdf(path: Path) -> str:
+        from pypdf import PdfReader
+        reader = PdfReader(str(path))
+        return "\n".join(page.extract_text() or "" for page in reader.pages)
+
+    @staticmethod
+    def _parse_json(path: Path) -> str:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        return json.dumps(data, ensure_ascii=False, indent=2)
+
+    def _chunk_text(self, text: str) -> list[str]:
+        chunks = []
+        start = 0
+        while start < len(text):
+            end = start + self.chunk_size
+            chunks.append(text[start:end])
+            start = end - self.chunk_overlap
+            if start >= len(text):
+                break
+        return [c.strip() for c in chunks if c.strip()]
+
+    def _embed(self, text: str) -> list[float]:
+        response = self._client.embeddings.create(
+            model=self.embedding_model,
+            input=text,
+        )
+        return response.data[0].embedding

llm_agent_base/llm_connection_config.py

@@ -0,0 +1,22 @@
+import os
+from dataclasses import dataclass
+from typing import Optional
+
+from openai import OpenAI
+
+
+@dataclass
+class LLMConnectionConfig:
+    model: str
+    base_url: str = "https://openrouter.ai/api/v1"
+    api_key: Optional[str] = None
+    embedding_model: str = "openai/text-embedding-3-small"
+
+    def get_api_key(self) -> str:
+        key = self.api_key or os.environ.get("OPENROUTER_API_KEY")
+        if not key:
+            raise ValueError("API key required: pass api_key or set OPENROUTER_API_KEY")
+        return key
+
+    def build_client(self) -> OpenAI:
+        return OpenAI(api_key=self.get_api_key(), base_url=self.base_url)

llm_agent_base/tool_calling.py

@@ -0,0 +1,100 @@
+import inspect
+import json
+from typing import Callable, Union, get_args, get_origin, get_type_hints
+
+_JSON_TYPE_MAP = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+}
+
+
+def _is_optional(tp) -> bool:
+    return get_origin(tp) is Union and type(None) in get_args(tp)
+
+
+def _unwrap_optional(tp):
+    args = [a for a in get_args(tp) if a is not type(None)]
+    return args[0] if args else str
+
+
+def _to_json_type(tp) -> str:
+    if _is_optional(tp):
+        tp = _unwrap_optional(tp)
+    return _JSON_TYPE_MAP.get(tp, "string")
+
+
+def build_tool_schema(fn: Callable) -> dict:
+    hints = get_type_hints(fn)
+    hints.pop("return", None)
+    sig = inspect.signature(fn)
+
+    properties = {}
+    required = []
+    for name, param in sig.parameters.items():
+        tp = hints.get(name, str)
+        properties[name] = {"type": _to_json_type(tp)}
+        if not _is_optional(tp) and param.default is inspect.Parameter.empty:
+            required.append(name)
+
+    return {
+        "type": "function",
+        "function": {
+            "name": fn.__name__,
+            "description": inspect.getdoc(fn) or "",
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+            },
+        },
+    }
+
+
+def execute_tool_loop(
+    client,
+    model: str,
+    messages: list,
+    tools: dict[str, tuple[Callable, dict]],
+    debug: bool = False,
+) -> str:
+    """Run the agentic tool-calling loop and return the final text response."""
+    tool_schemas = [schema for _, schema in tools.values()]
+
+    while True:
+        kwargs = {"model": model, "messages": messages}
+        if tool_schemas:
+            kwargs["tools"] = tool_schemas
+
+        response = client.chat.completions.create(**kwargs)
+        choice = response.choices[0]
+        msg = choice.message
+
+        if choice.finish_reason != "tool_calls" or not msg.tool_calls:
+            return msg.content
+
+        messages.append(msg)
+
+        for tc in msg.tool_calls:
+            fn, _ = tools.get(tc.function.name, (None, None))
+            if fn is None:
+                result = f"Error: unknown tool '{tc.function.name}'"
+                if debug:
+                    print(f"[debug] LLM called unknown tool '{tc.function.name}'")
+            else:
+                try:
+                    args = json.loads(tc.function.arguments)
+                    result = str(fn(**args))
+                    if debug:
+                        print(f"[debug] tool '{tc.function.name}' args={args} result={result}")
+                except Exception as e:
+                    result = f"Error: {e}"
+
+            messages.append({
+                "role": "tool",
+                "tool_call_id": tc.id,
+                "content": result,
+            })

llm_agent_base-0.1.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: llm-agent-base
+Version: 0.1.0
+Summary: Lightweight Python framework for building LLM agents with tool calling and RAG
+Author-email: Paweł Gryka <pawel.m.gryka@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mksochota16/llm-agent-base
+Project-URL: Repository, https://github.com/mksochota16/llm-agent-base
+Keywords: llm,agent,rag,openai,tool-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai>=2.0.0
+Requires-Dist: faiss-cpu>=1.7.0
+Requires-Dist: pypdf>=4.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: python-dotenv>=1.0.0
+
+# llm-agent-base
+
+A lightweight Python base for building LLM agents with tool calling and retrieval-augmented generation (RAG). It works with any OpenAI-compatible API (OpenRouter, OpenAI, local models via Ollama, etc.).
+
+## Features
+
+- **Tool calling** — register plain Python functions as LLM-callable tools; schemas are built automatically from type hints and docstrings
+- **RAG** — ingest a folder of documents (`.txt`, `.md`, `.json`, `.pdf`) into a FAISS vector index and inject relevant chunks into every prompt
+- **Pipelines** — chain multiple agents so each agent's output becomes the next agent's input
+- **Debug mode** — optional logging of tool calls and knowledge retrievals
+
+## Project structure
+
+```
+agent_base.py           # AgentBase class
+agent_pipeline_base.py  # AgentPipelineBase class
+tool_calling.py         # Schema building and tool-call execution loop
+knowledge_base.py       # Document ingestion, embedding, and FAISS retrieval
+llm_connection_config.py# LLM client configuration
+knowledge/              # Knowledge files (subdirectory per topic)
+```
+
+## Setup
+
+**1. Install dependencies**
+
+```bash
+pip install -r requirements.txt
+```
+
+**2. Configure environment**
+
+Copy `.env` and fill in your credentials:
+
+```env
+OPENROUTER_API_KEY=your-api-key-here
+MODEL=openai/gpt-4o-mini
+BASE_URL=https://openrouter.ai/api/v1
+```
+
+The default `BASE_URL` points to [OpenRouter](https://openrouter.ai), which gives access to many models through a single API key. You can swap it for the OpenAI base URL or any other compatible endpoint.
+
+## Usage
+
+### Basic agent
+
+```python
+from agent_base import AgentBase
+from llm_connection_config import LLMConnectionConfig
+
+config = LLMConnectionConfig(model="openai/gpt-4o-mini", api_key="...")
+
+agent = AgentBase(
+    system_prompt="You are a helpful assistant.",
+    llm_config=config,
+)
+
+print(agent.run("What is the capital of France?"))
+```
+
+### Tool calling
+
+Register any Python function as a tool. The function name becomes the tool name, the docstring becomes its description, and the type hints define the parameter schema.
+
+```python
+def get_weather(city: str) -> str:
+    """Return the current weather for a given city."""
+    return f"The weather in {city} is sunny and 22°C."
+
+def add(a: int, b: int) -> int:
+    """Add two integers and return the result."""
+    return a + b
+
+agent = AgentBase(
+    system_prompt="You are a helpful assistant. Use the available tools when needed.",
+    llm_config=config,
+)
+agent.register_tool(get_weather)
+agent.register_tool(add)
+
+print(agent.run("What is the weather in Tokyo and what is 10 + 20?"))
+```
+
+`register_tool` can also be used as a decorator:
+
+```python
+@agent.register_tool
+def search_orders(order_id: str) -> str:
+    """Look up an order by ID."""
+    ...
+```
+
+### RAG (knowledge base)
+
+Place your documents in a folder (organised into subdirectories by topic). Call `ingest_knowledge` once to embed and index them, then `run` as normal — relevant chunks are automatically injected into the system prompt.
+
+```
+knowledge/
+├── topic/
+│   └── overview.txt
+├── products/
+│   ├── faq.md
+│   └── pricing.json
+└── support/
+    └── sla.md
+```
+
+```python
+agent = AgentBase(
+    system_prompt="You are a product assistant. Answer using only the provided context.",
+    llm_config=config,
+    knowledge_folder_path="knowledge",
+    knowledge_index_dir=".kb_index",  # where the FAISS index is saved
+    knowledge_top_k=3,                # number of chunks injected per prompt
+)
+
+# Build and persist the index (run once, or when documents change)
+agent.ingest_knowledge(save=True)
+
+# On subsequent runs, load from disk instead of re-embedding
+# agent.load_knowledge()
+
+print(agent.run("Who founded the company and when?"))
+```
+
+### Agent pipelines
+
+Chain agents so the output of one becomes the input of the next:
+
+```python
+from agent_pipeline_base import AgentPipelineBase
+
+researcher = AgentBase(
+    system_prompt="Extract the key facts from the user's question.",
+    llm_config=config,
+)
+writer = AgentBase(
+    system_prompt="Turn the provided facts into a concise, friendly summary.",
+    llm_config=config,
+)
+
+pipeline = AgentPipelineBase(agents=[researcher, writer])
+print(pipeline.run("Tell me about the Acme Corp product lineup."))
+```
+
+### Debug mode
+
+Pass `debug=True` to any agent to print tool invocations and knowledge retrievals to stdout:
+
+```python
+agent = AgentBase(..., debug=True)
+```
+
+```
+[debug] Retrieving knowledge
+[debug] tool 'get_weather' args={'city': 'Tokyo'} result=The weather in Tokyo is sunny and 22°C.
+```

llm_agent_base-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+llm_agent_base/__init__.py,sha256=OXswBWRHp2RbBAFqAOuKubnREFBzvJbp3x2JdXRSALY,436
+llm_agent_base/agent_base.py,sha256=t49EfsnmlTwPSed_9w9DKdYsMoqjOWqfhtb4TgDuJ18,2364
+llm_agent_base/agent_pipeline_base.py,sha256=99FEKfn9ZsKxbWFkNysGP7ubksWXOwrtYkFEYj_a9BI,300
+llm_agent_base/knowledge_base.py,sha256=Y6zWzvTYw8lRFLFWnzEaPiDDCh-FBoxO9GgnXaXMOa0,5206
+llm_agent_base/llm_connection_config.py,sha256=urd4HpwU2XkF7K_iC8zgryXsufUdkn7dxUKsiFie6Ko,641
+llm_agent_base/tool_calling.py,sha256=n04S9XSViBj01zAUqmQBQLKVtGL2gs7MKVWbSaNkVa0,2851
+llm_agent_base-0.1.0.dist-info/METADATA,sha256=UjRjdJE5PT7h7izM00QM9Z9ecyNMdpvp7XZByHfhhgY,5808
+llm_agent_base-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+llm_agent_base-0.1.0.dist-info/top_level.txt,sha256=MFNYEHY1in6nbChJGeVLrzBIlGm9sJ-pXQpaXT5BmjM,15
+llm_agent_base-0.1.0.dist-info/RECORD,,

llm_agent_base-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

llm_agent_base-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+llm_agent_base