rag-titan 0.1.0__tar.gz

rag_titan-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environments
+.venv/
+env/
+venv/
+.env
+.env.*
+!.env.example
+
+# Vector databases / local storage
+data/
+*.sqlite3
+*.db
+chroma_db/
+qdrant_storage/
+
+# Observability / caches
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS / IDE
+.DS_Store
+.idea/
+.vscode/
+# Packaging / build output
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Docs build output
+site/

rag_titan-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project are written here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and the project uses [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-11-10
+
+### Added
+- First release of `rag-titan`.
+- RAG types: `SimpleRAG` and `AdaptiveRAG`.
+- `RAGTitan` class: index files and ask questions in two lines.
+- `rag-titan` command line tool (`ask` and `chat`).
+- Building blocks: PDF/DOCX loaders, word chunker, Ollama LLM and embedder,
+  in-memory vector store, keyword reranker, grounded generator.
+- Tool-calling `BaseAgent` with an example `MathAgent`.
+- Tests that run without Ollama, docs site, and PyPI publish workflow.
+- Animated flow diagrams (SVG) for every capability, with worked examples.

rag_titan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kumar Nishant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rag_titan-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: rag-titan
+Version: 0.1.0
+Summary: A Swiss Army knife for RAG: simple, adaptive and more RAG types in one beginner-friendly package.
+Project-URL: Homepage, https://github.com/aion7891/rag-titan
+Project-URL: Documentation, https://aion7891.github.io/rag-titan
+Project-URL: Repository, https://github.com/aion7891/rag-titan
+Project-URL: Issues, https://github.com/aion7891/rag-titan/issues
+Project-URL: Changelog, https://github.com/aion7891/rag-titan/blob/main/CHANGELOG.md
+Author: Kumar Nishant
+License: MIT License
+        
+        Copyright (c) 2026 Kumar Nishant
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: embeddings,llm,ollama,rag,retrieval-augmented-generation,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: ollama>=0.4.0
+Requires-Dist: pypdf>=4.0
+Requires-Dist: pytest>=8.4.2
+Requires-Dist: python-docx>=1.1
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# rag-titan
+
+**A Swiss Army knife for RAG (Retrieval-Augmented Generation).**
+
+`rag-titan` puts many types of RAG in one small, beginner-friendly Python
+package. Every part (loader, chunker, embedder, vector store, reranker,
+generator) is a small class you can read in a minute and replace with your own.
+
+[![PyPI](https://img.shields.io/pypi/v/rag-titan.svg)](https://pypi.org/project/rag-titan/)
+[![Python](https://img.shields.io/pypi/pyversions/rag-titan.svg)](https://pypi.org/project/rag-titan/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/aion7891/rag-titan/blob/main/LICENSE)
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/overview.svg" alt="rag-titan overview: indexing and answering" width="100%"></p>
+
+## Features
+
+| RAG type   | How it works                                                        |
+|------------|---------------------------------------------------------------------|
+| `simple`   | Retrieve → Rerank → Generate                                        |
+| `adaptive` | Route the question → Retrieve → Check evidence → Rewrite and retry  |
+
+More RAG types (corrective, hybrid, multi-query, graph, agentic, ...) are
+planned. See the [roadmap](https://github.com/aion7891/rag-titan/blob/main/docs/roadmap.md).
+
+- Runs **100% locally** with [Ollama](https://ollama.com), so your data stays on your machine.
+- Reads **PDF** and **DOCX** files.
+- Answers are **grounded** in your documents and **cite** the chunks they used.
+- Every part is swappable. You only need to inherit from one base class.
+- Includes a `rag-titan` command line tool.
+
+### Simple RAG
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/simple-rag.svg" alt="Simple RAG flow with example scores" width="100%"></p>
+
+### Adaptive RAG
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/adaptive-rag.svg" alt="Adaptive RAG flow with routes and retries" width="100%"></p>
+
+## Installation
+
+```bash
+pip install rag-titan
+```
+
+Then install [Ollama](https://ollama.com/download) and pull the default models:
+
+```bash
+ollama pull gemma3:4b          # chat model
+ollama pull nomic-embed-text   # embedding model
+```
+
+## Quick start
+
+```python
+from rag_titan import RAGTitan
+
+rag = RAGTitan(rag_type="simple")        # or "adaptive"
+rag.index(["handbook.pdf", "policy.docx"])
+
+print(rag.ask("How many leave days do I get?"))
+# You get 20 leave days every year [chunk_0].
+```
+
+Change any setting in code:
+
+```python
+rag = RAGTitan(
+    rag_type="adaptive",
+    settings={"llm_model": "llama3.2", "chunk_size": 200, "reranker": "none"},
+)
+```
+
+## Command line
+
+```bash
+rag-titan ask  --files handbook.pdf --question "How many leave days?"
+rag-titan chat --files handbook.pdf policy.docx --rag-type adaptive
+```
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/cli.svg" alt="rag-titan command line demo" width="100%"></p>
+
+## Configuration
+
+Settings come from environment variables or a `.env` file. Copy
+[`.env.example`](https://github.com/aion7891/rag-titan/blob/main/.env.example) to get started. Every setting has a default.
+
+| Variable        | Default                  | Meaning                      |
+|-----------------|--------------------------|------------------------------|
+| `LLM_MODEL`     | `gemma3:4b`              | Chat model used for answers  |
+| `EMBED_MODEL`   | `nomic-embed-text`       | Embedding model              |
+| `OLLAMA_HOST`   | `http://localhost:11434` | Ollama server address        |
+| `CHUNK_SIZE`    | `150`                    | Words per chunk              |
+| `CHUNK_OVERLAP` | `30`                     | Words shared between chunks  |
+| `RERANKER`      | `keyword`                | `keyword` or `none`          |
+
+See the [configuration docs](https://github.com/aion7891/rag-titan/blob/main/docs/configuration.md) for the full list.
+
+## How it works
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/indexing.svg" alt="Indexing pipeline: load, chunk, embed, store" width="100%"></p>
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/architecture.svg" alt="Every building block is swappable" width="100%"></p>
+
+## Agents
+
+A small tool-calling agent loop is included. See the [agents docs](https://github.com/aion7891/rag-titan/blob/main/docs/agents.md).
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/agent.svg" alt="Agent loop with an example trace" width="100%"></p>
+
+## Project layout
+
+```
+src/rag_titan/
+├── app.py            RAGTitan: the easy, all-in-one class
+├── cli.py            the `rag-titan` command
+├── config.py         settings from .env / environment
+├── factory.py        builds the right class for each setting
+├── prompts.py        every RAG prompt in one place
+├── llm/              chat models (Ollama)
+├── loaders/          PDF and DOCX readers
+├── chunking/         split text into chunks
+├── embeddings/       text -> vectors
+├── vector_stores/    save and search vectors
+├── retrieval/        retriever + rerankers
+├── generation/       write the final answer
+├── pipelines/        indexing pipeline
+├── rag_types/        simple and adaptive RAG
+├── agents/           tool-calling agents
+└── utils/            logging
+```
+
+## Documentation
+
+Full docs live in [`docs/`](https://github.com/aion7891/rag-titan/blob/main/docs/index.md). To view them locally:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](https://github.com/aion7891/rag-titan/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/aion7891/rag-titan/blob/main/LICENSE)

rag_titan-0.1.0/README.md

@@ -0,0 +1,147 @@
+# rag-titan
+
+**A Swiss Army knife for RAG (Retrieval-Augmented Generation).**
+
+`rag-titan` puts many types of RAG in one small, beginner-friendly Python
+package. Every part (loader, chunker, embedder, vector store, reranker,
+generator) is a small class you can read in a minute and replace with your own.
+
+[![PyPI](https://img.shields.io/pypi/v/rag-titan.svg)](https://pypi.org/project/rag-titan/)
+[![Python](https://img.shields.io/pypi/pyversions/rag-titan.svg)](https://pypi.org/project/rag-titan/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/aion7891/rag-titan/blob/main/LICENSE)
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/overview.svg" alt="rag-titan overview: indexing and answering" width="100%"></p>
+
+## Features
+
+| RAG type   | How it works                                                        |
+|------------|---------------------------------------------------------------------|
+| `simple`   | Retrieve → Rerank → Generate                                        |
+| `adaptive` | Route the question → Retrieve → Check evidence → Rewrite and retry  |
+
+More RAG types (corrective, hybrid, multi-query, graph, agentic, ...) are
+planned. See the [roadmap](https://github.com/aion7891/rag-titan/blob/main/docs/roadmap.md).
+
+- Runs **100% locally** with [Ollama](https://ollama.com), so your data stays on your machine.
+- Reads **PDF** and **DOCX** files.
+- Answers are **grounded** in your documents and **cite** the chunks they used.
+- Every part is swappable. You only need to inherit from one base class.
+- Includes a `rag-titan` command line tool.
+
+### Simple RAG
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/simple-rag.svg" alt="Simple RAG flow with example scores" width="100%"></p>
+
+### Adaptive RAG
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/adaptive-rag.svg" alt="Adaptive RAG flow with routes and retries" width="100%"></p>
+
+## Installation
+
+```bash
+pip install rag-titan
+```
+
+Then install [Ollama](https://ollama.com/download) and pull the default models:
+
+```bash
+ollama pull gemma3:4b          # chat model
+ollama pull nomic-embed-text   # embedding model
+```
+
+## Quick start
+
+```python
+from rag_titan import RAGTitan
+
+rag = RAGTitan(rag_type="simple")        # or "adaptive"
+rag.index(["handbook.pdf", "policy.docx"])
+
+print(rag.ask("How many leave days do I get?"))
+# You get 20 leave days every year [chunk_0].
+```
+
+Change any setting in code:
+
+```python
+rag = RAGTitan(
+    rag_type="adaptive",
+    settings={"llm_model": "llama3.2", "chunk_size": 200, "reranker": "none"},
+)
+```
+
+## Command line
+
+```bash
+rag-titan ask  --files handbook.pdf --question "How many leave days?"
+rag-titan chat --files handbook.pdf policy.docx --rag-type adaptive
+```
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/cli.svg" alt="rag-titan command line demo" width="100%"></p>
+
+## Configuration
+
+Settings come from environment variables or a `.env` file. Copy
+[`.env.example`](https://github.com/aion7891/rag-titan/blob/main/.env.example) to get started. Every setting has a default.
+
+| Variable        | Default                  | Meaning                      |
+|-----------------|--------------------------|------------------------------|
+| `LLM_MODEL`     | `gemma3:4b`              | Chat model used for answers  |
+| `EMBED_MODEL`   | `nomic-embed-text`       | Embedding model              |
+| `OLLAMA_HOST`   | `http://localhost:11434` | Ollama server address        |
+| `CHUNK_SIZE`    | `150`                    | Words per chunk              |
+| `CHUNK_OVERLAP` | `30`                     | Words shared between chunks  |
+| `RERANKER`      | `keyword`                | `keyword` or `none`          |
+
+See the [configuration docs](https://github.com/aion7891/rag-titan/blob/main/docs/configuration.md) for the full list.
+
+## How it works
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/indexing.svg" alt="Indexing pipeline: load, chunk, embed, store" width="100%"></p>
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/architecture.svg" alt="Every building block is swappable" width="100%"></p>
+
+## Agents
+
+A small tool-calling agent loop is included. See the [agents docs](https://github.com/aion7891/rag-titan/blob/main/docs/agents.md).
+
+<p align="center"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/agent.svg" alt="Agent loop with an example trace" width="100%"></p>
+
+## Project layout
+
+```
+src/rag_titan/
+├── app.py            RAGTitan: the easy, all-in-one class
+├── cli.py            the `rag-titan` command
+├── config.py         settings from .env / environment
+├── factory.py        builds the right class for each setting
+├── prompts.py        every RAG prompt in one place
+├── llm/              chat models (Ollama)
+├── loaders/          PDF and DOCX readers
+├── chunking/         split text into chunks
+├── embeddings/       text -> vectors
+├── vector_stores/    save and search vectors
+├── retrieval/        retriever + rerankers
+├── generation/       write the final answer
+├── pipelines/        indexing pipeline
+├── rag_types/        simple and adaptive RAG
+├── agents/           tool-calling agents
+└── utils/            logging
+```
+
+## Documentation
+
+Full docs live in [`docs/`](https://github.com/aion7891/rag-titan/blob/main/docs/index.md). To view them locally:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Contributing
+
+Contributions are welcome. Please read [CONTRIBUTING.md](https://github.com/aion7891/rag-titan/blob/main/CONTRIBUTING.md).
+
+## License
+
+[MIT](https://github.com/aion7891/rag-titan/blob/main/LICENSE)

rag_titan-0.1.0/pyproject.toml

@@ -0,0 +1,83 @@
+# Packaging settings for rag-titan.
+# Build:   python -m build
+# Publish: twine upload dist/*   (or the GitHub "Publish" workflow)
+
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rag-titan"
+dynamic = ["version"]
+description = "A Swiss Army knife for RAG: simple, adaptive and more RAG types in one beginner-friendly package."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "Kumar Nishant" }]
+keywords = ["rag", "retrieval-augmented-generation", "llm", "ollama", "embeddings", "vector-search"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Education",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Indexing",
+]
+dependencies = [
+    "numpy>=1.24",
+    "ollama>=0.4.0",
+    "pypdf>=4.0",
+    "pytest>=8.4.2",
+    "python-docx>=1.1",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.6",
+    "build>=1.2",
+    "twine>=5.0",
+]
+docs = [
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.25",
+]
+
+[project.urls]
+Homepage = "https://github.com/aion7891/rag-titan"
+Documentation = "https://aion7891.github.io/rag-titan"
+Repository = "https://github.com/aion7891/rag-titan"
+Issues = "https://github.com/aion7891/rag-titan/issues"
+Changelog = "https://github.com/aion7891/rag-titan/blob/main/CHANGELOG.md"
+
+[project.scripts]
+rag-titan = "rag_titan.cli:main"
+
+# the version lives in one place: src/rag_titan/__init__.py
+[tool.hatch.version]
+path = "src/rag_titan/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rag_titan"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/rag_titan", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]

rag_titan-0.1.0/src/rag_titan/__init__.py

@@ -0,0 +1,31 @@
+"""
+rag-titan: a Swiss Army knife for Retrieval-Augmented Generation (RAG).
+
+Quick start:
+    from rag_titan import RAGTitan
+
+    rag = RAGTitan(rag_type="simple")
+    rag.index(["handbook.pdf"])
+    print(rag.ask("How many leave days do I get?"))
+"""
+
+from rag_titan.app import RAGTitan
+from rag_titan.config import get_settings
+from rag_titan.factory import RAG_TYPES, build_rag, build_rag_parts
+from rag_titan.rag_types.adaptive.adaptive_rag import AdaptiveRAG
+from rag_titan.rag_types.simple_rag import SimpleRAG
+from rag_titan.utils.logger import setup_logging
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RAGTitan",
+    "SimpleRAG",
+    "AdaptiveRAG",
+    "RAG_TYPES",
+    "build_rag",
+    "build_rag_parts",
+    "get_settings",
+    "setup_logging",
+    "__version__",
+]

rag_titan-0.1.0/src/rag_titan/agents/__init__.py

@@ -0,0 +1,6 @@
+"""Tool-calling agents."""
+
+from rag_titan.agents.base_agent import BaseAgent
+from rag_titan.agents.math_agent import MathAgent
+
+__all__ = ["BaseAgent", "MathAgent"]

rag_titan-0.1.0/src/rag_titan/agents/base_agent.py

@@ -0,0 +1,81 @@
+"""
+Base class for every tool-calling agent.
+
+The loop:
+    think (LLM) -> call tools -> send results back -> repeat
+    until the LLM answers without calling a tool, or max_steps is reached.
+
+To build a new agent, inherit from BaseAgent and pass a prompt and tools.
+"""
+
+from rag_titan.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class BaseAgent:
+    """
+    A simple agent that lets an LLM call Python functions.
+
+    Args:
+        llm: any BaseLLM that supports tool calling.
+        system_prompt: instructions that describe the agent's job.
+        tools: list of plain Python functions the LLM may call.
+        max_steps: stop after this many think/tool rounds.
+    """
+
+    def __init__(self, llm, system_prompt, tools, max_steps=5):
+        self.llm = llm
+        self.system_prompt = system_prompt
+        self.tools = tools
+        self.tools_by_name = {tool.__name__: tool for tool in tools}
+        self.max_steps = max_steps
+        self.reset()
+
+    def reset(self):
+        """Forget the conversation and start fresh."""
+        self.messages = [{"role": "system", "content": self.system_prompt}]
+
+    def run(self, query):
+        """
+        Answer one user message, calling tools as needed.
+
+        Args:
+            query: the user's message.
+
+        Returns:
+            The agent's final answer text.
+        """
+        self.messages.append({"role": "user", "content": query})
+
+        for step in range(1, self.max_steps + 1):
+            logger.info("Agent step %d: thinking...", step)
+            response = self.llm.chat(self.messages, tools=self.tools)
+            self.messages.append(response["message"])
+
+            # no tool calls means the LLM has given its final answer
+            if not response["tool_calls"]:
+                return response["content"]
+
+            for tool_call in response["tool_calls"]:
+                result = self._run_tool(tool_call)
+                self.messages.append(self.llm.tool_result_message(tool_call, result))
+
+        return "Maximum steps reached without a final answer."
+
+    def _run_tool(self, tool_call):
+        """Run one tool safely. Errors are returned as text to the LLM."""
+        name = tool_call["name"]
+        arguments = tool_call["arguments"]
+        tool = self.tools_by_name.get(name)
+
+        if tool is None:
+            result = f"Error: unknown tool '{name}'"
+        else:
+            try:
+                result = tool(**arguments)
+            except Exception as error:
+                result = f"Error while running {name}: {error}"
+
+        logger.info("Tool %s(%s) = %s", name, arguments, result)
+        return result

rag_titan-0.1.0/src/rag_titan/agents/math_agent.py

@@ -0,0 +1,29 @@
+"""
+A small example agent that solves math with tools.
+
+    from rag_titan.agents import MathAgent
+    agent = MathAgent(llm)
+    print(agent.run("What is (12 + 8) * 3?"))
+"""
+
+from rag_titan.agents.base_agent import BaseAgent
+from rag_titan.agents.prompts import MATH_AGENT_PROMPT
+from rag_titan.agents.tools.math_tools import MATH_TOOLS
+
+
+class MathAgent(BaseAgent):
+    """
+    Agent that uses add, subtract, multiply and divide tools.
+
+    Args:
+        llm: a BaseLLM whose model supports tool calling.
+        max_steps: stop after this many think/tool rounds.
+    """
+
+    def __init__(self, llm, max_steps=5):
+        super().__init__(
+            llm=llm,
+            system_prompt=MATH_AGENT_PROMPT,
+            tools=MATH_TOOLS,
+            max_steps=max_steps,
+        )