# RavenEye

[![M8ven Score](https://m8ven.ai/badge/mcp/harsh313-b-raveneye-u4allv)](https://m8ven.ai/mcp/harsh313-b-raveneye-u4allv)

> **A modular multi-agent AI intelligence platform that discovers, analyzes, ranks, and summarizes high-value AI news and GitHub opportunities into actionable intelligence reports.**

---

# Overview

RavenEye automates the process of monitoring the rapidly evolving AI ecosystem.

Instead of manually browsing RSS feeds and GitHub every day, RavenEye continuously collects information from trusted sources, filters irrelevant content, ranks opportunities using transparent scoring, and generates a professional Markdown intelligence report.

The project follows a modular multi-agent architecture, allowing new intelligence sources and analytical capabilities to be added without redesigning the system.

---

# Features

## Implemented (Version 1.0)

- RSS news collection
- RSS parsing and HTML cleaning
- AI news categorization
- GitHub repository discovery
- Repository relevance scoring
- Opportunity ranking
- Duplicate filtering
- Automated Markdown report generation
- Multi-agent architecture
- Orchestrator-based workflow
- MCP (Model Context Protocol) integration
- Configuration-driven design

---

## Planned (Future Versions)

- Skills Intelligence Agent
- Internship Intelligence Agent
- arXiv Research Agent
- Hugging Face monitoring
- Reddit Intelligence Agent
- Conference tracking
- Personalized recommendations
- Historical trend analysis
- Web dashboard
- Notifications

---

# Architecture

```
                    User / CLI
                         │
                         ▼
                   Orchestrator
                         │
          ┌──────────────┼──────────────┐
          │              │              │
          ▼              ▼              ▼
      RSS Agent     GitHub Agent   Report Agent
          │              │              │
          └──────────────┼──────────────┘
                         ▼
              Markdown Intelligence Report
                         │
                         ▼
                   MCP Integration
```

---

# Project Structure

```text
RavenEye/

├── agents/
│   ├── base_agent.py
│   ├── rss_agent.py
│   ├── github_agent.py
│   └── report_agent.py
│
├── tools/
│   ├── rss_service.py
│   ├── github_service.py
│   ├── report_service.py
│   └── utils.py
│
├── Integrations/
│   └── server.py
│
├── briefs/
├── Documents/
│
├── orchestrator.py
├── config.py
├── main.py
└── README.md
```

---

# Workflow

1. RSS Agent collects AI news.
2. GitHub Agent discovers promising repositories.
3. Results are filtered and ranked.
4. The Report Agent generates a Markdown intelligence report.
5. The Orchestrator coordinates the complete pipeline.
6. The MCP server exposes RavenEye tools for external clients.

---

# Technologies Used

- Python 3
- GitHub REST API
- RSS Feeds
- feedparser
- BeautifulSoup4
- Requests
- Markdown
- MCP (Model Context Protocol)

---

# Running RavenEye

Clone the repository:

```bash
git clone <repository-url>
cd RavenEye
```

Install dependencies:

```bash
pip install -r requirements.txt
```

Run:

```bash
python3 main.py
```

A new intelligence report will be generated inside the **briefs/** directory.

---

# MCP Integration

RavenEye exposes its capabilities through the Model Context Protocol (MCP).

Available tools include:

- scan_rss
- scan_github
- generate_report
- run_pipeline

The project can be tested using the MCP Inspector.

---

# Documentation

| Document | Description |
|-----------|-------------|
| SPEC.md | Functional and non-functional requirements |
| ARCHITECTURE.md | System architecture |
| AGENTS.md | Agent responsibilities and development rules |
| ROADMAP.md | Development roadmap |
| PROJECT_STATE.md | Current implementation status |

---

# Current Status

**Version:** 1.0.0

Current implementation includes:

- RSS Intelligence
- GitHub Intelligence
- Report Generation
- Multi-Agent Architecture
- Orchestrator
- MCP Integration

The Version 1 pipeline is fully operational and capable of generating end-to-end intelligence reports.

---

# Future Roadmap

Version 1.1

- Skills Intelligence Agent
- Internship Intelligence Agent

Version 2

- arXiv integration
- Hugging Face integration
- Reddit Intelligence
- Trend analysis
- Personalized recommendations

---

# License

This project is released under the MIT License.

---

# Author

**Harsh Bhati**

RavenEye was developed as a modular AI intelligence platform following modern software engineering principles, emphasizing modularity, maintainability, extensibility, and transparency.