AI Agentic - GitHub Repository README Summarizer

An intelligent tool that automatically generates concise summaries of GitHub repository README files using AI

🎯 Overview

AI Agentic is a Node.js application that automatically fetches README files from multiple GitHub repositories, generates AI-powered summaries, and compiles them into a comprehensive markdown document. The tool supports multiple AI backends including OpenAI's GPT models and local Ollama instances.

✨ Features

• Multi-Repository Processing: Process multiple GitHub repositories in a single run
• AI-Powered Summarization: Generate concise, technical summaries using AI
• Multiple AI Backends: Support for OpenAI GPT models and local Ollama instances
• Flexible Output: Save summaries locally or push directly to GitHub
• Dry Run Mode: Test functionality without making changes
• Comprehensive Error Handling: Detailed logging and error reporting
• Environment-Based Configuration: Secure configuration management

🏗️ Architecture

The project consists of three main scripts, each serving different use cases:

Scripts Overview

Script	Purpose	AI Backend	Output
summarizer.js	Basic OpenAI integration	OpenAI GPT	GitHub Repository
summarizer-local.js	Local file output	OpenAI GPT	Local Files
summarizer-ollama.js	Ollama integration	Local Ollama	GitHub Repository or Local

🚀 Quick Start

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm
• GitHub Personal Access Token
• OpenAI API Key (for OpenAI scripts) or Ollama (for Ollama script)

Installation

1. Clone the repository

   git clone <repository-url>
   cd ai-agentic

2. Install dependencies

   pnpm install

3. Configure environment variables

   cp .env.example .env.local

4. Edit .env.local with your credentials

   # GitHub Configuration
   GITHUB_TOKEN=your_github_personal_access_token
   GITHUB_TARGET_REPO=your-username/ai-docs
   
   # OpenAI Configuration (for OpenAI scripts)
   OPENAI_API_KEY=your_openai_api_key
   
   # Ollama Configuration (for Ollama script)
   OLLAMA_BASE_URL=http://localhost:11434
   OLLAMA_MODEL=llama2

📖 Usage

Available Scripts

The project provides several npm scripts for different use cases:

# Development - Local file output with OpenAI
pnpm run dev

# OpenAI - Push to GitHub repository
pnpm run openapi

# Ollama - Dry run (local output)
pnpm run ollama:dry

# Ollama - Push to GitHub repository
pnpm run ollama

Configuration Options

Environment Variables

Variable	Description	Default	Required
GITHUB_TOKEN	GitHub Personal Access Token	-	Yes
GITHUB_TARGET_REPO	Target repository for summaries	stephanbit/ai-docs	No
OPENAI_API_KEY	OpenAI API Key	-	For OpenAI scripts
OLLAMA_BASE_URL	Ollama server URL	http://localhost:11434	No
OLLAMA_MODEL	Ollama model name	llama2	No

Source Repositories

Edit the SOURCE_REPOS array in the scripts to specify which repositories to process:

const SOURCE_REPOS = [
  "stephanbit/eze-cli",
  "stephanbit/micro-frontend-pages", 
  "stephanbit/vue-cli-plugin-easycloud"
];

🔧 Detailed Usage Examples

1. Local Development with OpenAI

Generate summaries and save them locally:

pnpm run dev

This will:

• Fetch README files from configured repositories
• Generate AI summaries using OpenAI
• Save results to summaries/README_SUMMARIES.md

2. Push to GitHub with OpenAI

Generate summaries and push to a GitHub repository:

pnpm run openapi

This will:

• Process all source repositories
• Generate AI summaries
• Create or update the target GitHub repository
• Commit the summaries file

3. Local Ollama Processing

Test with local Ollama without pushing to GitHub:

pnpm run ollama:dry

This will:

• Use local Ollama instance for AI processing
• Save results locally
• Not make any GitHub changes

4. Production Ollama Processing

Use Ollama and push to GitHub:

pnpm run ollama

This will:

• Process repositories with local Ollama
• Automatically create target repository if needed
• Push summaries to GitHub

🛠️ Development

Project Structure

ai-agentic/
├── summarizer.js              # Basic OpenAI → GitHub script
├── summarizer-local.js        # OpenAI → Local files script  
├── summarizer-ollama.js       # Ollama → GitHub/Local script
├── package.json               # Dependencies and scripts
├── summaries/                 # Local output directory
│   └── README_SUMMARIES.md    # Generated summaries
└── README.md                  # This file

Key Dependencies

• @octokit/rest: GitHub API client
• axios: HTTP client for AI API calls
• dotenv: Environment variable management
• yargs: Command-line argument parsing (Ollama script)

Adding New Features

1. New AI Backend: Create a new script following the existing pattern
2. Custom Output Formats: Modify the compileSummaries() function
3. Additional Repository Sources: Extend the repository fetching logic

🔍 Troubleshooting

Common Issues

1. GitHub 404 Errors

• Cause: Repository doesn't exist or insufficient permissions
• Solution: Ensure the target repository exists and your token has repo scope

2. OpenAI API Errors

• Cause: Invalid API key or model name
• Solution: Verify your API key and use a valid model (e.g., gpt-4o-mini)

3. Ollama Connection Errors

• Cause: Ollama not running or wrong URL
• Solution: Start Ollama and verify the base URL

4. Permission Denied

• Cause: GitHub token lacks required scopes
• Solution: Ensure token has repo and public_repo scopes

Debug Mode

Enable detailed logging by checking the console output. All scripts provide comprehensive error messages and status updates.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Octokit for GitHub API integration
• OpenAI for AI capabilities
• Ollama for local AI processing

📞 Support

For issues and questions:

1. Check the troubleshooting section above
2. Review the error logs for specific details
3. Open an issue on GitHub with detailed error information

---

Made with ❤️ for the open source community