granite4-local-agents

Local IBM Granite AI Content Refiner

Table of Contents

• Overview
• Features
• Prerequisites
• Quick Start
• Installation
• Configuration
• Usage
• Security Features
• Architecture
• Project Structure
• Contributing
• Known Issues
• License

Overview

This project implements a Local Multi-Agent AI Content Refinement System using IBM's newest state-of-the-art Granite Nano models via Ollama. It leverages a Generator-Critic-Summarizer-Research workflow to iteratively produce high-quality content based on a given task, incorporating external research and rigorous quality evaluation.

The system runs entirely locally, ensuring data privacy and security, and is designed for production environments with built-in cybersecurity features.

Disclaimer: This agentic system is experimental and must undergo additional evaluation before being deployed into a production environment.

Features

• Multi-Agent Workflow: Generator, Critic, Summarizer, and Research agents collaborate to refine content.
• Local Execution: Runs entirely on your local machine using Ollama.
• IBM Granite Models: Leverages ibm/granite4:350m, ibm/granite4:1b, and ibm/granite4:3b models.
• External Research: Integrates with the Tavily API for up-to-date information retrieval.
• Iterative Refinement: Continuously improves content based on quality scores until a threshold is met.
• Quality Assurance: Built-in critic agent evaluates content and provides specific feedback.
• Security-First Design: Implements secure API key management, input sanitization, audit logging, and more.
• Configurable: Easily configurable via YAML file for models, workflow parameters, and security settings.

Prerequisites

• Python 3.8 or higher - Download
• Ollama - Install
• IBM Granite models via Ollama:
  • ibm/granite4:350m (Generator - fastest)
  • ibm/granite4:1b (Critic - medium)
  • ibm/granite4:3b (Summarizer & Researcher - largest)
• Tavily API Key - Get free key

Quick Start

# 1. Clone the repository
git clone <your-repository-url>
cd granite4-local-agents

# 2. Install dependencies
pip install -r requirements.txt

# 3. Start Ollama
ollama serve

# 4. Pull IBM Granite models
ollama pull ibm/granite4:350m
ollama pull ibm/granite4:1b
ollama pull ibm/granite4:3b

# 5. Set up environment
cp .env.example .env
# Edit .env and add your TAVILY_API_KEY

# 6. Run the application
python granite4-local-main.py --task "Write a blog post about AI"

For detailed installation instructions, see SETUP.md.

Installation

1. Clone the Repository

git clone <your-repository-url>
cd granite4-local-agents

2. Create Virtual Environment (Recommended)

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Python Dependencies

pip install -r requirements.txt

This installs:

• aiohttp - Async HTTP client
• pyyaml - YAML configuration support
• tenacity - Retry logic with exponential backoff
• requests - Synchronous HTTP for validation

4. Install and Configure Ollama

Install Ollama from ollama.com, then:

# Start Ollama server (in a separate terminal)
ollama serve

# Pull required IBM Granite models
ollama pull ibm/granite4:350m
ollama pull ibm/granite4:1b
ollama pull ibm/granite4:3b

Important: All model names must include the ibm/ prefix.

5. Set Up Environment Variables

# Copy environment template
cp .env.example .env

# Edit .env and add your Tavily API key
# TAVILY_API_KEY=your_actual_api_key_here

Get your free Tavily API key from tavily.com.

Security Note: Never commit your .env file to version control!

Configuration

The system uses config.yaml for configuration. You can customize:

Model Configuration

models:
  generator: "ibm/granite4:350m"      # Fast model for content generation
  critic: "ibm/granite4:1b"           # Medium model for evaluation
  summarizer: "ibm/granite4:3b"       # Large model for summarization
  researcher: "ibm/granite4:3b"       # Large model for research

Workflow Settings

workflow:
  max_iterations: 5           # Maximum refinement cycles
  quality_threshold: 8.0      # Target quality score (0-10)

Research Configuration

tavily:
  search_depth: "advanced"    # "basic" or "advanced"
  max_results: 3              # Number of search results
  timeout: 30                 # Request timeout in seconds

Security Settings

security:
  audit_log_file: "agentic_workflow_audit.log"
  enable_pii_redaction: true
  enable_audit_logging: true

For all configuration options, see the config.yaml file.

Usage

Command Line

Run with a specific task:

python granite4-local-main.py --task "Your detailed content creation task here"

Interactive Mode

Run without arguments to be prompted:

python granite4-local-main.py
# You will be asked: "🎯 Enter your content creation task: "

Example

python granite4-local-main.py --task "Write a comprehensive blog post about the benefits of renewable energy for residential use."

Output

The system will:

1. 🔍 Conduct research using Tavily API
2. 📝 Generate content using ibm/granite4:350m
3. 🎯 Evaluate quality using ibm/granite4:1b
4. 🔄 Refine iteratively based on feedback
5. 📊 Summarize progress using ibm/granite4:3b
6. ✅ Deliver final content with quality score

Example output:

🚀 Starting content refinement for: Write a blog post about renewable energy
============================================================
🔍 Conducting initial research...
🔄 Iteration 1/5
📝 Generating initial content...
🎯 Evaluating content quality...
   Quality Score: 7.5/10
📊 Summarizing progress...
...
✅ Quality threshold reached! Score: 8.2
============================================================
🎉 CONTENT REFINEMENT COMPLETE!
============================================================
📊 Final Quality Score: 8.2/10
🔄 Iterations Completed: 3
⏱️  Total Time: 45.3s
🔒 Session ID: a3f5e8d2c1b4a6f9

Security Features

This system implements enterprise-grade cybersecurity best practices:

🔒 Secure API Key Management

• API keys loaded from environment variables
• Never hardcoded in source code
• Excluded from version control via .gitignore

🛡️ Input Sanitization & PII Detection

• Automatic detection of sensitive data
• Regex-based PII redaction for:
  • Email addresses
  • Social Security Numbers (SSN)
  • Credit card numbers
  • Phone numbers
• Sanitization before processing and logging

📝 Tamper-Evident Audit Logging

• Comprehensive event logging with timestamps
• Session tracking with unique IDs
• Cryptographic hash chains (SHA-256) for tamper detection
• Audit trail for all content generation and API calls
• Logs saved to agentic_workflow_audit.log

🔐 Encrypted Communications

• All external API calls over HTTPS
• Secure Tavily API integration
• TLS encryption for web requests

🎯 Principle of Least Privilege

• Minimal system resource access
• Environment variable-based configuration
• Controlled file system operations
• Restricted network access

✅ Context Integrity Validation

• Cryptographic hashing of context data
• Verification of data integrity between workflow steps
• Chain-of-custody for generated content

Audit logs location: agentic_workflow_audit.log

Architecture

The system consists of several specialized components:

Core Components

• AIContentRefiner: Main orchestrator managing the workflow
• GeneratorAgent: Creates/refines content using ibm/granite4:350m
• CriticAgent: Evaluates quality using ibm/granite4:1b
• SummarizerAgent: Maintains context using ibm/granite4:3b
• ResearchAgent: Analyzes tasks and coordinates research using ibm/granite4:3b

Support Components

• OllamaClient: Handles local Ollama API communication
• TavilyResearcher: Interfaces with Tavily API for web research
• SecurityManager: Centralizes security functions (logging, sanitization, hashing)

Workflow Diagram

Task Input
    ↓
Research Phase (TavilyResearcher)
    ↓
Content Generation (GeneratorAgent - ibm/granite4:350m)
    ↓
Quality Evaluation (CriticAgent - ibm/granite4:1b)
    ↓
Progress Summary (SummarizerAgent - ibm/granite4:3b)
    ↓
Quality Check → [Pass] → Final Output
    ↓          ↑
   [Fail]      |
    └─────────┘
  (Iterate with feedback)

Project Structure

granite4-local-agents/
├── granite4-local-main.py      # Main application code
├── requirements.txt            # Python dependencies
├── config.yaml                 # Configuration file
├── .env.example               # Environment variable template
├── .gitignore                 # Git ignore rules
├── README.md                  # This file
├── SETUP.md                   # Detailed setup guide
├── CONTRIBUTING.md            # Contribution guidelines
├── BUGS.md                    # Known issues tracker
├── LICENSE                    # MIT License
└── Granite.jpg                # Project logo

Generated Files (Not in Repository)

├── .env                       # Your environment variables (git-ignored)
├── agentic_workflow_audit.log # Security audit logs (git-ignored)
├── context_history.log        # Workflow context history (git-ignored)
└── outputs/                   # Generated content (git-ignored)

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting pull requests.

Important Notes for Contributors

1. Always use ibm/ prefix for Granite model references
2. Follow Python PEP 8 style guidelines
3. Add type hints to all functions
4. Include docstrings for public methods
5. Test changes thoroughly before submitting
6. Update documentation as needed
7. Never commit sensitive data or API keys

Areas for Contribution

• Bug fixes (see BUGS.md)
• Documentation improvements
• Test coverage
• Performance optimizations
• Security enhancements
• New agent capabilities
• Model integrations

Known Issues

See BUGS.md for a complete list of known issues and their status.

Critical Issues

⚠️ Syntax Error on Line 201: The TavilyResearcher has a syntax error that needs fixing before deployment.

⚠️ Hardcoded Config: The Python file contains hardcoded configuration that should be loaded from config.yaml.

Please check BUGS.md for details and workarounds.

Troubleshooting

Common Issues

"TAVILY_API_KEY environment variable not set"

• Solution: Create a .env file with your API key
• See SETUP.md for details

"Cannot connect to Ollama"

• Solution: Run ollama serve in a separate terminal
• Ensure Ollama is installed correctly

"Required model not found"

• Solution: Pull missing models with ollama pull ibm/granite4:XXX
• Verify models with ollama list

For more troubleshooting help, see SETUP.md.

Documentation

• SETUP.md - Comprehensive setup guide
• CONTRIBUTING.md - How to contribute
• BUGS.md - Known issues and bugs
• config.yaml - Configuration reference

Requirements

See requirements.txt for Python dependencies:

• aiohttp >=3.9.0
• pyyaml >=6.0.1
• tenacity >=8.2.3
• requests >=2.31.0

License

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

Acknowledgments

• IBM for the Granite AI models
• Ollama for local model hosting
• Tavily for research API
• IBM Champions Program

Authors

© 2025 Julian A. Gonzalez, Thomas Mertens

---

Star ⭐ this repository if you find it useful!

Report Bug · Request Feature · Documentation