AI Research Agent 🤖

An interactive AI research and writing assistant with a beautiful terminal UI, powered by local LLMs through Ollama. Built in Rust with multi-agent orchestration for complex research, coding, and writing tasks.

✨ Features

🎯 Core Capabilities

• Interactive Terminal UI: Beautiful TUI with markdown rendering, syntax highlighting, and live progress updates
• Multi-Agent Orchestration: Intelligent task decomposition and delegation to specialized sub-agents
• Local LLM Power: Uses Ollama for complete privacy - your data never leaves your machine
• Web Research: Integrated SearXNG search for finding papers, articles, and technical information
• File Operations: Read, write, and edit files in a secure workspace directory
• Session Persistence: Auto-save conversations and resume previous research sessions

🤖 Specialized Sub-Agents

• Programmer: Write complete programs with cargo integration (build, test, compile)
• Code Review: Security analysis, best practices, idiomatic Rust patterns
• Code Analyzer: Extract APIs, document architecture, analyze module structure
• Software Architect: Design validation, SOLID principles, ADR generation
• Scientific Researcher: Academic literature search and optional paper writing
• Proofreader: Academic editing with grammar, citation, and clarity improvements
• Research Evaluator: Gap analysis to ensure comprehensive research coverage
• Web Researcher: Deep web research with intelligent link following
• Crates Documenter: Search crates.io and generate usage guides
• Data Analyzer: Statistical analysis on CSV/JSON datasets
• JSON Processor: Transform, validate, and convert JSON data
• Template Generator: Project scaffolding (Rust crates, LaTeX papers, configs)
• Designer: UI/UX design and prototyping
• Frida Expert: Dynamic instrumentation for reverse engineering (optional)

🔧 Advanced Features

• Automatic Error Recovery: Failed steps trigger recovery analysis and retry strategies
• Replanning: Exploratory research can trigger plan updates based on findings
• Smart Tool Selection: Planning agent chooses optimal tools vs. sub-agents
• Progress Tracking: Real-time visibility into multi-step operations
• Cargo Integration: Build, test, check, and clippy for Rust development
• Syntax Highlighting: Code blocks beautifully rendered in terminal
• Markdown Support: Full markdown rendering for rich formatting

📋 Prerequisites

1. Rust (1.70 or later)

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

2. Ollama - Required for LLM inference

   # macOS/Linux
   curl -fsSL https://ollama.ai/install.sh | sh
   
   # Or download from https://ollama.ai
   

3. A Local Model - Pull at least one model

   # Recommended models:
   ollama pull llama3.2          # General purpose
   ollama pull qwen2.5:14b       # Excellent for coding
   ollama pull deepseek-r1:14b   # Great for research
   

4. Start Ollama - Make sure it's running

   ollama serve
   

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/ai-research-agent.git
cd ai-research-agent

# Configure environment
cp .env.example .env
# Edit .env to set your preferred model

# Build and run
cargo build --release
cargo run

First Run

The application launches in interactive TUI mode:

┌─────────────────────────────────────────────┐
│  AI Research Agent                          │
│  Model: llama3.2                            │
│  Workspace: ./workspace                     │
└─────────────────────────────────────────────┘

> What would you like to research?

Example Queries

Try these to explore different capabilities:

# Web Research
> Research quantum computing and find recent papers from 2024-2025

# Code Generation
> Write a Rust program that parses JSON and validates schemas

# Code Review
> Review the code in workspace/main.rs for security issues

# Academic Writing
> Research transformer models, then write a 2-page paper with citations

# Data Analysis
> Analyze the CSV file at workspace/data.csv and show statistics

# Create Project
> Generate a new Rust library crate for HTTP clients

⌨️ Keyboard Shortcuts

Key	Action
i / Enter	Enter editing mode
Esc	Exit editing mode
Ctrl+Q	Quit and save session
m	Model picker (switch models)
t	Toggle progress messages
z	Toggle Zotero integration
w	Toggle web search

🔧 Configuration

The application is configured via .env file. See .env.example for all options.

Essential Settings

# Model Selection
OLLAMA_MODEL=llama3.2

# Ollama Connection
OLLAMA_API_BASE_URL=http://localhost:11434

# Workspace Directory
WORKSPACE_PATH=./workspace

# Multi-Agent Orchestration
ENABLE_ORCHESTRATION=true
MAX_TOOL_ITERATIONS=15

# File Operations
ENABLE_FILE_OPERATIONS=true
MAX_FILE_SIZE_MB=50

Advanced Settings

# Temperature (0.0 = deterministic, 1.0 = creative)
TEMPERATURE=0.7

# Search Configuration
SEARXNG_BASE_URL=https://searx.be
MAX_SEARCH_RESULTS=5

# Session Management
REPL_AUTO_SAVE=true
REPL_MAX_HISTORY=10

# Error Recovery
ENABLE_RECOVERY=true
ENABLE_RECOVERY_RETRY=true
MAX_RECOVERY_RETRIES_PER_STEP=1

# Timeouts
OLLAMA_TIMEOUT_SECS=300
CARGO_TEST_TIMEOUT=120

Security Features

# File Operations (workspace-restricted)
ENABLE_FILE_OPERATIONS=true
WORKSPACE_PATH=./workspace  # All ops scoped here
MAX_FILE_SIZE_MB=50

# Frida (disabled by default)
ENABLE_FRIDA=false
FRIDA_PROCESS_ALLOWLIST=  # Explicit allowlist required
FRIDA_REQUIRE_CONFIRMATION=true

📁 Project Structure

ai-research-agent/
├── src/
│   ├── main.rs                    # Entry point, CLI args
│   ├── config.rs                  # Configuration management
│   ├── agent.rs                   # Main ResearchAgent
│   ├── tools.rs                   # Tool implementations
│   ├── orchestrator/
│   │   ├── mod.rs                 # Orchestration framework
│   │   ├── planner.rs             # Task planning agent
│   │   ├── protocol.rs            # Data structures
│   │   └── subagents/             # Specialized agents
│   │       ├── programmer.rs
│   │       ├── scientific_researcher.rs
│   │       ├── code_review.rs
│   │       └── ...
│   ├── repl/
│   │   ├── app.rs                 # TUI event loop
│   │   ├── session.rs             # Session persistence
│   │   └── markdown.rs            # Markdown rendering
│   └── ollama_client.rs           # Ollama API client
├── logs/                          # Session history
├── workspace/                     # File operations directory
├── .env.example                   # Configuration template
├── Cargo.toml                     # Dependencies
├── CLAUDE.md                      # Developer guide
└── README.md                      # This file

🏗️ Architecture

Multi-Agent Orchestration

User Query
    ↓
Main Agent (ResearchAgent)
    ↓
Planning Agent (analyzes complexity)
    ↓
Execution Plan (steps with strategies)
    ↓
Step Execution
    ├→ Direct Tool Call (web_search, read_file, etc.)
    ├→ Sub-Agent Delegation (Programmer, Researcher, etc.)
    └→ Synthesis (aggregate results)
    ↓
Result Aggregation
    ↓
Response to User

Planning and Execution

1. Query Analysis: Planning agent decomposes complex queries
2. Strategy Selection: Choose between direct tools or specialized sub-agents
3. Sequential Execution: Steps run in order, respecting dependencies
4. Error Recovery: Failed steps trigger recovery analysis
5. Replanning: Research findings can trigger plan updates
6. Result Synthesis: Main agent aggregates all results

Tool Calling Flow

• Uses Rig framework's Agent::dynamic_chat() for automatic tool loops
• Configurable MAX_TOOL_ITERATIONS prevents infinite loops
• Tools return structured results for context injection
• Sub-agents return SubAgentResult with summaries and metadata

🧪 Development

Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Check without building
cargo check

# Run clippy lints
cargo clippy

Testing

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_name

# Run integration tests
cargo test orchestrator::

Code Quality

# Format code
cargo fmt

# Check formatting
cargo fmt -- --check

# Generate documentation
cargo doc --open

# Run with debug logging
cargo run -- --verbose

Adding a Sub-Agent

1. Create src/orchestrator/subagents/your_agent.rs
2. Implement SubAgent trait with system prompt
3. Register in SubAgentRegistry::new()
4. Add variant to SubAgentType enum
5. Update planning agent prompt
6. Test with example query

See CLAUDE.md for detailed development guide.

📖 Usage Examples

Research and Writing

> Research transformers in NLP and write a 3-page survey paper

[Agent plans: Research → Gap Analysis → Writing → Proofreading]
[ScientificResearcher] Searching arXiv, IEEE, ACM...
[ResearchEvaluator] Analyzing coverage gaps...
[ScientificResearcher] Creating outline and draft...
[Proofreader] Checking grammar and citations...

✓ Paper saved to workspace/transformer_survey.md
✓ References saved to workspace/references.bib

Code Development

> Write a Rust HTTP client with retry logic and test it

[Programmer] Creating HTTP client implementation...
[Programmer] Running cargo build...
[Programmer] Running cargo test...
[CodeReview] Analyzing for best practices...

✓ Code saved to workspace/http_client.rs
✓ Tests saved to workspace/http_client_tests.rs
✓ All tests passed (5/5)

Data Analysis

> Analyze workspace/sales_data.csv and find trends

[DataAnalyzer] Reading CSV file...
[DataAnalyzer] Computing statistics...

## Analysis Results
- Total records: 1,245
- Date range: 2023-01-01 to 2025-12-31
- Revenue trend: +15% YoY
- Top category: Electronics (42% of sales)

[Full report saved to workspace/analysis_report.md]

Session Management

# Resume most recent session
cargo run -- --resume

# Load specific session by ID
cargo run -- --session 20260403_183000

# Use custom workspace
cargo run -- --workspace ~/research-project

🤝 Contributing

Contributions are welcome! Areas for improvement:

• Additional sub-agents (translator, validator, etc.)
• More tool integrations (Git, Docker, etc.)
• UI enhancements (charts, tables, images)
• Performance optimizations
• Test coverage expansion
• Documentation improvements

Please:

1. Fork the repository
2. Create a feature branch
3. Run tests and clippy
4. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Darshan vichhi (Aarambh)

🙏 Acknowledgments

Built with amazing open-source technologies:

• Rig - Rust LLM framework
• Ollama - Local LLM inference
• Ratatui - Terminal UI framework
• Tokio - Async runtime
• SearXNG - Privacy-respecting search

🐛 Troubleshooting

Ollama Connection Issues

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama
ollama serve

Model Not Found

# List available models
ollama list

# Pull missing model
ollama pull llama3.2

File Permission Errors

# Create workspace directory
mkdir -p workspace
chmod 755 workspace

Timeout Errors

Increase timeouts in .env:

OLLAMA_TIMEOUT_SECS=600
MAX_TOOL_ITERATIONS=20

📚 Documentation

• CLAUDE.md - Comprehensive developer guide
• .env.example - Full configuration reference
• Session logs in logs/ - Previous conversations for reference

🗺️ Roadmap

• Plugin system for custom tools and agents
• Web UI alternative to TUI
• Support for multiple LLM backends (OpenAI, Anthropic)
• Vector database integration for RAG
• Collaborative multi-user sessions
• Export to PDF/HTML/LaTeX
• Git integration for code projects
• Jupyter notebook support

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Star ⭐ this repo if you find it useful!

Made with 🦀 and ❤️ in Rust