{"id":39445206,"url":"https://github.com/mbeacom/gemini-processors-research-agent-showcase","last_synced_at":"2026-01-18T04:24:19.616Z","repository":{"id":305208572,"uuid":"1020997423","full_name":"mbeacom/gemini-processors-research-agent-showcase","owner":"mbeacom","description":"A showcase of Gemini processors for building agents versus without them","archived":false,"fork":false,"pushed_at":"2025-07-18T18:23:10.000Z","size":89,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-18T23:22:49.168Z","etag":null,"topics":["agent","ai","asyncio","demo","gemini","gemini-processor","genai","generative-ai","google","multimodal","processor","processors","python","showcase"],"latest_commit_sha":null,"homepage":"https://www.markbeacom.com/blog/architecture/genai/processors-announcement","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mbeacom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-16T18:02:52.000Z","updated_at":"2025-07-18T18:23:40.000Z","dependencies_parsed_at":"2025-07-18T23:25:31.927Z","dependency_job_id":"cc7e9d44-0064-48ef-8bec-3c27546bffc1","html_url":"https://github.com/mbeacom/gemini-processors-research-agent-showcase","commit_stats":null,"previous_names":["mbeacom/gemini-processors-research-agent-showcase"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mbeacom/gemini-processors-research-agent-showcase","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbeacom%2Fgemini-processors-research-agent-showcase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbeacom%2Fgemini-processors-research-agent-showcase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbeacom%2Fgemini-processors-research-agent-showcase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbeacom%2Fgemini-processors-research-agent-showcase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mbeacom","download_url":"https://codeload.github.com/mbeacom/gemini-processors-research-agent-showcase/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mbeacom%2Fgemini-processors-research-agent-showcase/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28529515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T00:39:45.795Z","status":"online","status_checked_at":"2026-01-18T02:00:07.578Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","asyncio","demo","gemini","gemini-processor","genai","generative-ai","google","multimodal","processor","processors","python","showcase"],"created_at":"2026-01-18T04:24:19.551Z","updated_at":"2026-01-18T04:24:19.600Z","avatar_url":"https://github.com/mbeacom.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gemini Processors Research Agent Showcase\n\nA side-by-side comparison demonstrating the power and elegance of **Gemini Processors** versus traditional Python development for building AI research agents.\n\n## 🎯 What This Showcases\n\nThis project implements the **exact same AI research agent** using two completely different approaches:\n\n1. **Traditional Python** (`traditional/`) - Manual control flow, boilerplate code, complex error handling\n2. **Gemini Processors** (`processors/`) - Declarative pipelines, automatic error handling, composable architecture\n\n**The functionality is identical - the development experience is dramatically different.**\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Python 3.13+\n- [uv](https://docs.astral.sh/uv/) for dependency management\n- Google Gemini API key\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/mbeacom/gemini-processors-research-agent-showcase.git\ncd gemini-processors-research-agent-showcase\n\n# Set your Gemini API key\nexport GEMINI_API_KEY=\"your-api-key-here\"\n```\n\n### Run Traditional Implementation\n\n```bash\ncd traditional\nuv sync --all-groups\nuv run python agent.py\n```\n\n### Run Gemini Processors Implementation\n\n```bash\ncd processors\nuv sync --all-groups\nuv run python agent.py\n```## 📊 The Dramatic Difference\n\n| Aspect | Traditional Python | Gemini Processors |\n|--------|-------------------|-------------------|\n| **Lines of Code** | ~450+ | ~370+ |\n| **Error Handling** | Manual try/catch everywhere | Automatic through metadata |\n| **Composability** | Monolithic functions | Reusable `@processor_function` |\n| **Pipeline Definition** | Nested function calls | Declarative `+` composition |\n| **Testability** | Complex mocking required | Easy processor unit testing |\n\n## 🔧 What Both Agents Do\n\n1. **Load Tasks**: Read research topics from `sources.json`\n2. **Validate**: Use Pydantic models to ensure data quality\n3. **Fetch Content**: Securely retrieve content from URLs\n4. **Generate Summaries**: Use Google Gemini AI for intelligent summaries\n5. **Create Report**: Generate a professional Markdown newsletter\n\n## 💡 Key Insights\n\n### Traditional Approach Pain Points\n- ❌ **Boilerplate Everywhere**: Repetitive error handling, logging, state management\n- ❌ **Monolithic Functions**: Large functions mixing multiple concerns\n- ❌ **Manual State Passing**: Complex parameter threading between steps\n- ❌ **Error Prone**: Easy to miss edge cases and error conditions\n\n### Gemini Processors Advantages\n- ✅ **Declarative Pipelines**: `pipeline = processor1 + processor2 + processor3`\n- ✅ **Automatic Error Handling**: Metadata flows errors through the pipeline\n- ✅ **Single Responsibility**: Each processor has one clear purpose\n- ✅ **Composable \u0026 Reusable**: Mix and match processors for different workflows\n- ✅ **Built-in Concurrency**: Automatic parallel processing where possible\n\n## 🔍 Code Comparison\n\n### Traditional: Manual Everything\n```python\nasync def process_tasks(self):\n    \"\"\"Traditional approach - manual control flow\"\"\"\n    try:\n        # Manual loading with explicit error handling\n        raw_tasks = await self._load_tasks()\n\n        # Manual validation with state tracking\n        validated_tasks = []\n        for task in raw_tasks:\n            try:\n                validated = self._validate_task(task)\n                validated_tasks.append(validated)\n            except Exception as e:\n                self._handle_validation_error(task, e)\n\n        # Manual fetching with progress tracking\n        fetched_tasks = []\n        for i, task in enumerate(validated_tasks):\n            try:\n                content = await self._fetch_content(task)\n                fetched_tasks.append(content)\n                self._log_progress(i, len(validated_tasks))\n            except Exception as e:\n                self._handle_fetch_error(task, e)\n\n        # Manual summary generation...\n        # More boilerplate code continues...\n    except Exception as e:\n        self._handle_pipeline_error(e)\n```\n\n### Gemini Processors: Declarative Elegance\n\n```python\n# Gemini Processors approach - compose with + operator\nresearch_pipeline = (\n    load_tasks_from_json\n    + validate_task\n    + fetch_url_content\n    + filter_successful_fetches\n    + add_summary_prompt\n    + genai_model.GenaiModel(\n        api_key=api_key,\n        model_name=\"gemini-2.5-flash\"\n    )\n    + collect_summaries_for_report\n)\n\n# Execute the entire pipeline\nasync for result in research_pipeline(input_stream):\n    if result.metadata.get(\"status\") == \"completed\":\n        print(\"Pipeline completed successfully!\")\n```\n\n## 📁 Project Structure\n\n```bash\ngemini-processors-research-agent-showcase/\n├── assets               # Project assets (input data)\n│   └── sources.json     # Test data (valid \u0026 invalid entries)\n├── LICENSE              # The project license file\n├── processors           # Gemini Processors implementation\n│   ├── agent.py         # Processors-based agent\n│   ├── pyproject.toml   # Dependencies \u0026 tooling\n│   ├── README.md        # Processors approach docs\n│   └── uv.lock          # Dependencies \u0026 tooling\n├── README.md            # This file\n├── SHOWCASE.md          # Detailed comparison analysis\n└── traditional          # Manual Python implementation\n    ├── agent.py         # Traditional research agent\n    ├── pyproject.toml   # Dependencies \u0026 tooling\n    ├── README.md        # Traditional approach docs\n    └── uv.lock          # Dependencies \u0026 tooling\n```\n\n## 🎓 Learning Outcomes\n\nAfter exploring this showcase, you'll understand:\n\n- **Why declarative pipelines** are superior to imperative control flow\n- **How automatic error handling** eliminates boilerplate code\n- **The power of composable processors** for building complex workflows\n- **When to choose** Gemini Processors vs traditional approaches\n- **Migration strategies** for existing Python codebases\n\n## 🔗 Learn More\n\n- **[Blog Post: Gemini Processors Announcement](https://www.markbeacom.com/blog/architecture/genai/processors-announcement)** - Comprehensive overview and announcement\n- **[Detailed Comparison](SHOWCASE.md)** - In-depth analysis of both approaches\n- **[Gemini Processors Documentation](https://github.com/google-gemini/genai-processors)** - Official framework docs\n- **[Design Document](DESIGN_DOCUMENT.md)** - Technical architecture decisions\n\n## 🤝 Contributing\n\nFound an issue or want to improve the showcase? Contributions welcome!\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n---\n\n**Ready to see the future of AI application development?**\n\nStart with the [Traditional Implementation](traditional/) to experience the pain points, then discover the elegance of [Gemini Processors](processors/) - you'll never want to go back to manual control flow! 🚀\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbeacom%2Fgemini-processors-research-agent-showcase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmbeacom%2Fgemini-processors-research-agent-showcase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmbeacom%2Fgemini-processors-research-agent-showcase/lists"}