🧠 hoodaAgents — Local-First AI Agent Framework Powered by Ollama

hoodaAgents is a local-first AI assistant framework for building customizable AI agents that run on your own machine using Ollama, LangChain, and LangGraph.

It combines powerful open-source language models such as Qwen3 with intelligent tool usage, allowing local AI agents to reason, use tools, perform calculations, access optional live web search, and interact with external APIs — while keeping the core AI inference on your own hardware.

🚀 What is hoodaAgents?

hoodaAgents serves as a foundation for building modular, privacy-focused, and extensible local AI agents.

It is designed to support agents that can:

• 💬 Answer questions and maintain conversational context
• 🧠 Integrate persistent memory and RAG systems
• 🔍 Perform optional live web research through Tavily
• 🧮 Use local tools such as calculators and system utilities
• 🔧 Connect to custom tools, APIs, and workflows
• 🔌 Integrate with MCP-compatible tools and services
• 🖥️ Run locally through Ollama
• 🛡️ Keep model inference and private conversations on your machine
• 🤖 Expand into specialized or multi-agent AI systems

💡 Why hoodaAgents?

Many modern AI assistants depend heavily on cloud-hosted models and proprietary APIs.

hoodaAgents takes a different approach: local-first AI.

The language model runs through Ollama on your own hardware, giving you greater control over your models, prompts, tools, data, and agent architecture.

External services are optional. For example, hoodaAgents can operate completely offline when using only local tools, while features such as live web search can be enabled separately when needed.

The goal is simple:

Your AI. Your tools. Your machine.

🛠️ Built With

• Ollama — Runs open-source LLMs locally
• Qwen3 — Default tool-capable local language model
• ChatOllama — Connects Ollama models to the agent runtime
• LangChain — Provides agent and tool integrations
• LangGraph — Enables advanced stateful and multi-agent workflows
• Tavily — Optional real-time web search
• Python — Powers the modular hoodaAgents runtime

🏗️ Architecture

User
  ↓
hoodaAgents Python Runtime
  ↓
LangChain create_agent / LangGraph
  │
  ├── 🧮 Calculator
  ├── 🕐 Local Machine Time
  ├── 🔍 Tavily Search (optional)
  ├── 🧠 Memory / RAG
  ├── 🔌 MCP Tools
  └── 🛠️ Custom APIs & Tools
  ↓
ChatOllama
  ↓
hoodarunner/hoodaAgents
  ↓
Qwen3:8b

The Ollama model and hoodaAgents runtime are intentionally separate.

Ollama handles local model inference, while the Python agent runtime handles tools, workflows, memory, search, and agent orchestration.

This allows the underlying model to be replaced without rebuilding the entire hoodaAgents architecture.

🧩 Project Use Cases

hoodaAgents can serve as the foundation for:

• Personal local AI assistants
• AI research agents
• Local document assistants
• RAG and memory-augmented agents
• Coding assistants
• Prompt engineering experiments
• Privacy-focused AI applications
• MCP-powered assistants
• API automation agents
• Multi-agent systems
• Custom AI workflows and automation

📁 Project Structure

hoodaAgents/
├── Modelfile
├── README.md
├── requirements.txt
├── .env.example
├── main.py
│
├── agents/
│   ├── __init__.py
│   └── simple_agent.py
│
└── tools/
    ├── __init__.py
    ├── local_tools.py
    └── search.py

🧪 Getting Started

1. Install Ollama

Install Ollama for your operating system.

On supported Linux systems:

curl -fsSL https://ollama.com/install.sh | sh

2. Pull Qwen3

ollama pull qwen3:8b

3. Create the hoodaAgents Model

From the project directory:

ollama create hoodarunner/hoodaAgents -f Modelfile

Verify the model:

ollama show --modelfile hoodarunner/hoodaAgents

4. Run hoodaAgents Directly Through Ollama

ollama run hoodarunner/hoodaAgents

5. Create a Python Environment

Windows

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

6. Configure Optional Web Search

hoodaAgents can run without external search.

To enable Tavily, create a .env file based on .env.example:

TAVILY_API_KEY=your_key_here
HOODA_MODEL=hoodarunner/hoodaAgents

Without a Tavily API key, the assistant remains local and offline.

7. Run the Agent Framework

python main.py

You now have a local hoodaAgents assistant running through Ollama.

📦 Publishing to Ollama

After creating and testing the model locally, publish it to your Ollama account:

ollama push hoodarunner/hoodaAgents

Other machines can then retrieve it using:

ollama pull hoodarunner/hoodaAgents

and run it with:

ollama run hoodarunner/hoodaAgents

🛠️ Customize Your Agent

hoodaAgents is designed to be extended.

Modify agents/simple_agent.py and the tools/ directory to:

• Add new tools
• Add external APIs
• Add local file access
• Add MCP integrations
• Add vector databases
• Add persistent memory
• Add RAG pipelines
• Create specialized agents
• Build multi-agent workflows
• Connect additional Ollama models

You can also swap Qwen3 for another Ollama-compatible model depending on your hardware and use case.

🧠 Future Development

Planned areas for hoodaAgents include:

• Persistent long-term memory
• Memory-Augmented Generation (MAG)
• Local embeddings
• Vector database integration
• Local document RAG
• MCP client support
• Garmin and Strava integrations
• Coding and filesystem agents
• Specialized research agents
• Multi-agent orchestration
• Voice interaction
• Local web interfaces
• Additional privacy and permission controls

🔒 Local-First Philosophy

hoodaAgents is built around a simple principle:

Local by default. External when useful. User-controlled always.

The core model runs locally through Ollama. External capabilities such as web search and APIs are optional extensions rather than requirements.

This makes hoodaAgents suitable for experimentation with powerful AI agents while maintaining greater control over where inference happens and how data is handled.

---

Made with ❤️ by Yash Hooda

🤖 hoodaAgents — Build locally. Extend freely. Own your AI.