agent-reasoning 1.0.7
Transform LLMs into robust problem-solving agents with advanced reasoning strategies
Requires Python: >=3.10
Keywords: llm, reasoning, agents, cot, tot, react

# Agent Reasoning: The Thinking Layer

![License](https://img.shields.io/badge/license-MIT-green)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![PyPI](https://img.shields.io/pypi/v/agent-reasoning)
![Ollama](https://img.shields.io/badge/backend-Ollama-black)
![Reasoning](https://img.shields.io/badge/reasoning-CoT%20|%20ToT%20|%20ReAct-purple)
![Status](https://img.shields.io/badge/status-experimental-orange)

![](https://raw.githubusercontent.com/jasperan/agent-reasoning/main/gif/arena_mode.gif)

## Vision & Purpose

The **Reasoning Layer** is the cognitive engine of the AI stack. While traditional LLMs excel at token generation, they often struggle with complex planning, logical deduction, and self-correction.

This repository transforms standard Open Source models (like `gemma3`, `llama3`) into robust problem solvers by wrapping them in advanced cognitive architectures. It implements findings from key research papers (CoT, ToT, ReAct) to give models "agency" over their thinking process.

> **"From predicting the next token to predicting the next thought."**

---

## 📦 Installation

### From PyPI (Recommended)

```bash
pip install agent-reasoning

# With server dependencies (for the reasoning gateway):
pip install "agent-reasoning[server]"
```

### From Source

```bash
# Clone the repo
git clone https://github.com/jasperan/agent-reasoning.git
cd agent-reasoning

# Install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -e .
```

**Prerequisite**: [Ollama](https://ollama.com/) must be running locally, or you can connect to a remote Ollama instance.
```bash
ollama pull gemma3:270m
```

### Configuring Remote Ollama Endpoint

If you don't have Ollama installed locally, you can connect to a remote Ollama instance. Configuration is stored in `config.yaml` in the root directory of the repository.

**Option 1: Interactive CLI Configuration**
```bash
agent-reasoning
# Select "Configure Endpoint" from the menu
```

**Option 2: Server CLI Argument**
```bash
agent-reasoning-server --ollama-host http://192.168.1.100:11434
```

**Option 3: Direct Config File**

Copy the example config and edit it:
```bash
cp config.yaml.example config.yaml
```

Or create `config.yaml` in the project root:
```yaml
ollama:
  host: http://192.168.1.100:11434
```

**Option 4: Python API**
```python
from agent_reasoning import ReasoningInterceptor, set_ollama_host, get_ollama_host

# Check current endpoint
print(get_ollama_host())  # http://localhost:11434

# Set a new endpoint (persists to config file)
set_ollama_host("http://192.168.1.100:11434")

# Or specify directly without saving to config
client = ReasoningInterceptor(host="http://192.168.1.100:11434")
```

---

## 📓 Notebooks

Interactive Jupyter notebooks demonstrating agent reasoning capabilities:

| Name | Description | Stack | Link |
| ---- | ----------- | ----- | ---- |
| agent_reasoning_demo | Comprehensive demo of all reasoning strategies (CoT, ToT, ReAct, Self-Reflection) with benchmarks and comparisons | Ollama, Gemma3/Llama3, FastAPI | [![Open Notebook](https://img.shields.io/badge/Open%20Notebook-orange?style=flat-square)](https://github.com/jasperan/agent-reasoning/blob/main/notebooks/agent_reasoning_demo.ipynb) |

---

## 🚀 Features
**✅ Verified against ArXiv Papers**

*   **Plug & Play**: Use via Python Class or as a Network Proxy.
*   **Model Agnostic**: Works with any model served by Ollama.
*   **Advanced Architectures**:
    *   🔗 **Chain-of-Thought (CoT)** & **Self-Consistency**: Implements Majority Voting ($k$ samples) with temperature sampling.
    *   🌳 **Tree of Thoughts (ToT)**: BFS strategy with robust heuristic scoring and pruning.
    *   🛠️ **ReAct (Reason + Act)**: Real-time tool usage (**Web Search** via scraping, Wikipedia API, Calculator) with fallback/mock capabilities. External grounding implemented.
    *   🪞 **Self-Reflection**: Dynamic multi-turn Refinement Loop (Draft -> Critique -> Improve).
    *   🧩 **Decomposition & Least-to-Most**: Planning and sub-task execution.

---

## 💻 Usage

### 1. Interactive CLI (Recommended)
Access all agents, comparisons, and benchmarks via the rich CLI.

```bash
# If installed via pip:
agent-reasoning

# Or from source:
python agent_cli.py
```

**Interactive Experience:**
```text
╭────────────────────────────────────────────╮
│ AGENT REASONING CLI                        │
│ Advanced Cognitive Architectures (Gemma 3) │
╰────────────────────────────────────────────╯

? Select an Activity:
  Chat with Standard Agent
  Chain of Thought (CoT)
  Tree of Thoughts (ToT)
  ReAct (Tools + Web)
  ⚔️  ARENA: Run All Compare
  Select AI Model
  Exit
```

### 2. Python API (For Developers)
Use the `ReasoningInterceptor` as a drop-in replacement for your LLM client.

```python
from agent_reasoning import ReasoningInterceptor

client = ReasoningInterceptor()

# Append the strategy to the model name with a '+'
response = client.generate(
    model="gemma3:270m+tot",
    prompt="I have a 3-gallon and 5-gallon jug. How do I measure 4 gallons?"
)
print(response["response"])
```

**Using agents directly:**

```python
from agent_reasoning.agents import CoTAgent, ToTAgent, ReActAgent

# Create an agent
agent = CoTAgent(model="gemma3:270m")

# Stream responses
for chunk in agent.stream("Explain quantum entanglement step by step"):
    print(chunk, end="")
```

### 3. Reasoning Gateway Server
Run a proxy server that impersonates Ollama. This allows **any** Ollama-compatible app (LangChain, Web UIs) to gain reasoning capabilities without code changes.

```bash
# If installed via pip:
agent-reasoning-server --port 8080

# Or from source:
python server.py
```

Then configure your app:
*   **Base URL**: `http://localhost:8080`
*   **Model**: `gemma3:270m+cot` (or `+tot`, `+react`, etc.)

**Example:**
```bash
curl http://localhost:8080/api/generate -d '{
  "model": "gemma3:270m+cot",
  "prompt": "Why is the sky blue?"
}'
```

---

## 🧠 Architectures in Detail

| Architecture | Description | Best For | Papers |
|--------------|-------------|----------|--------|
| **Chain-of-Thought** | Step-by-step reasoning prompt injection. | Math, Logic, Explanations | [Wei et al. (2022)](https://arxiv.org/abs/2201.11903) |
| **Self-Reflection** | Draft -> Critique -> Refine loop. | Creative Writing, High Accuracy | [Shinn et al. (2023)](https://arxiv.org/abs/2303.11366) |
| **ReAct** | Interleaves Reasoning and Tool Usage. | Fact-checking, Calculations | [Yao et al. (2022)](https://arxiv.org/abs/2210.03629) |
| **Tree of Thoughts** | Explores multiple reasoning branches (BFS/DFS). | Complex Riddles, Strategy | [Yao et al. (2023)](https://arxiv.org/abs/2305.10601) |
| **Decomposed** | Breaks complex queries into sub-tasks. | Planning, Long-form answers | [Khot et al. (2022)](https://arxiv.org/abs/2210.02406) |
| **Recursive (RLM)** | Uses Python REPL to recursively process prompt variables. | Long-context processing | [Author et al. (2025)](https://arxiv.org/abs/2512.24601) |

---

## 📚 Appendix A: Extending the System

To add a new reasoning strategy (e.g., "Reviewer-Critic"), simply:

1.  Create a class in `src/agent_reasoning/agents/` inheriting from `BaseAgent`.
2.  Implement the `stream(self, query)` method.
3.  Register it in `AGENT_MAP` in `src/agent_reasoning/interceptor.py`.

```python
from agent_reasoning.agents.base import BaseAgent

class MyNewAgent(BaseAgent):
    def stream(self, query):
        yield "Thinking differently...\n"
        # ... your custom logic ...
        yield "Final Answer"
```

## 🔧 Appendix B: Troubleshooting

*   **Model Not Found**: Ensure you have pulled the base model (`ollama pull gemma3:270m`).
*   **Timeout / Slow**: ToT and Self-Reflection make multiple calls to the LLM. With larger models (Llama3 70b), this can take time.
*   **Hallucinations**: The default demo uses `gemma3:270m` which is extremely small and prone to logic errors. Switch to `gemma2:9b` or `llama3` for robust results.

---

## 📊 Benchmark Report (Example Outputs)

Below are real outputs generated by the `main.py` benchmark using `gemma3:270m`. Note that while the small model strives to follow the reasoning structures, its logic limitations highlight the importance of using larger models (e.g., `llama3` or `gemma2:9b`) for production.

### 1. Philosophy (Self-Consistency)
*Generates multiple reasoning paths and votes for the best answer.*

**Query:** "What is the meaning of life? Answer with a mix of biological and philosophical perspectives."
```text
[ConsistencyAgent]: Processing query via Self-Consistency (k=3)...
  Sample 1: [Detailed biological perspective on propagation...]
  Sample 2: [Philosophical view on existentialism and purpose...]
  Sample 3: [Synthesis of both views...]
Majority Logic: [Aggregated Best Answer from Votes]
```

### 2. Logic (Tree of Thoughts)
*Explores multiple branches (BFS) to solve riddles.*

**Query:** "I have a 3-gallon jug and a 5-gallon jug. How can I measure exactly 4 gallons of water?"
```text
[ToTAgent]: Processing query via Tree of Thoughts (BFS)...
Thinking via Tree of Thoughts (Depth=3, Width=2)...

[Step 1/3 - Exploring branches]
  Path Score: 0.0
  Path Score: 1.0

[Step 2/3 - Exploring branches]
  Path Score: 1.0
  Path Score: 1.0
  Path Score: 0.1

[Step 3/3 - Exploring branches]
  Path Score: 1.0 (Found solution state)

[Best Logic Trace selected. Generating Final Answer]
**Final Answer:**
1. Pour water from the 5-gallon jug into the 3-gallon jug.
2. You now have 2 gallons left in the 5-gallon jug.
3. Empty the 3-gallon jug.
4. Pour the 2 gallons from the 5-gallon jug into the 3-gallon jug.
5. Fill the 5-gallon jug again.
6. Pour from the 5-gallon jug into the 3-gallon jug until full (needs 1 gallon).
7. You are left with exactly 4 gallons in the 5-gallon jug.
```

### 3. Planning (Decomposed Agent)
*Breaks down complex tasks into sub-problems.*

**Query:** "Plan a detailed 3-day itinerary for Tokyo for a history buff who loves samurais and tea."
```text
[DecomposedAgent]: Decomposing the problem...

Sub-tasks Plan:
1.  **Define the Scope:** What historical period and specific area of Tokyo will the itinerary cover?
2.  **Identify Key Historical Sites:** What historical sites will the itinerary focus on?
3.  **Determine Traveler's Interests:** What types of historical sites will the itinerary include?
4.  **Outline the Itinerary:** What activities and attractions will be included in each day?
5.  **Estimate Duration:** How long will the itinerary last?

[DecomposedAgent]: Solving sub-task: 1. Define the Scope...
[DecomposedAgent]: Solving sub-task: 2. Identify Key Historical Sites...
...
Final Answer: [Detailed 3-day plan covering Meiji Shrine, Tea Ceremonies, and Samurai Museum]
```

### 4. Tool Use (ReAct Agent)
*Interleaves thought, action, and observation to solve problems.*

**Query:** "Who is the current CEO of Google? Calculate the square root of 144."
```text
[ReActAgent]: Processing query with ReAct...

--- Step 1 ---
Agent: Action: web_search[current CEO of Google]
Observation: Sundar Pichai is the current CEO of Google.
Final Answer: Sundar Pichai

Running web_search...
Observation: [1] Sundar Pichai - Wikipedia: ... He is the chief executive officer (CEO) of Alphabet Inc. and its subsidiary Google.
```

---

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.