🚀 Composio API Research Agent

Enterprise-grade B2B API research and agentic buildability evaluator — fully automated, end-to-end.

Feed it a target app list → Get structured developer portal audit data, auth methods, gating protocols, and an interactive intelligence dashboard. Zero manual steps.

Quick Start • Architecture • Pipeline Stages • Demo • Engineering • Roadmap

---

📌 Problem Statement

Auditing external SaaS APIs before building agent toolkits is slow, manual, and doesn't scale across hundreds of integrations:

Manual Workflow (per App)	Time Spent
🔍 Researching developer documentation	~15 min
🔑 Identifying supported API auth methods	~10 min
🛡️ Auditing developer account access & gates	~15 min
📋 Evaluating toolkit buildability & blockers	~10 min
Total for 100 apps	~83 Hours

This agentic pipeline reduces the entire 100-app audit to under 3 minutes.

---

🏛️ Architecture & Data Flow

                        ┌─────────────────────┐
                        │   📋 App Target List │
                        │      (100 Apps)     │
                        └──────────┬──────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  STAGE 1 — Target Parser    │
                    │  Loads name & hints         │
                    │  Excludes local dev cache   │
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  STAGE 2 — Grounded Agent   │
                    │  Gemini 2.5-Flash + Search  │
                    │  Queries docs & extracts info│
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  STAGE 3 — Verification Loop│
                    │  verify_agent.py (Audit)     │
                    │  Compares passes vs targets │
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  STAGE 4 — Data Clustering   │
                    │  analyze_data.py            │
                    │  Auth/Access Stats Summary  │
                    └──────────────┬──────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │  STAGE 5 — HTML Compiler     │
                    │  build_dashboard.py         │
                    │  Generates index.html UI    │
                    └─────────────────────────────┘

Each stage's output feeds directly into the next, culminating in a single portable, interactive HTML dashboard.

---

🗂️ Project Structure

composio-api-research-agent/
│
├── 📄 research_agent.py              # Stage 1 & 2 — Research pipeline & structured extraction
├── 📄 verify_agent.py                # Stage 3 — Validation loop (15-app audit)
├── 📄 analyze_data.py                # Stage 4 — Statistical clustering & segmentation
├── 📄 build_dashboard.py              # Stage 5 — HTML dashboard compilation
│
├── 📂 screenshots/                   # Project visual assets
│   └── dashboard_preview.png         # Full interactive case study screenshot
│
├── 📄 index.html                     # Final self-contained interactive dashboard
├── 📄 raw_results.json               # Raw JSON database for all 100 apps
├── 📄 analysis_summary.json          # Statistical aggregates and easy wins
├── 📄 verification_report.json       # Audit details and accuracy shift logs
├── 📄 requirements.txt               # Python dependencies
├── 📄 .env.example                   # Environment template
└── 📄 .env                           # Local credentials (git-ignored)

---

⚡ Engineering Highlights

What makes this implementation production-grade:

🎨 Decoupled Static UI Compilation

The final dashboard is built by a compilation script (build_dashboard.py) that reads JSON aggregates and injects them directly into the HTML file. This ensures the output is 100% portable and runs offline without CORS errors.

🧠 Grounded LLM Agent

Uses the new google-genai SDK with Google Search grounding enabled. The agent crawls the web, reads current API documentation, and extracts info into structured Pydantic models.

🛡️ Double-Pass Verification

Features a dedicated validation script (verify_agent.py) that selects a random 15-app sample, compares unverified first-pass outputs with manual docs, and tracks accuracy progression.

🔡 Unicode & Legacy Terminal Protection

Includes print fallbacks that clean stdout strings, preventing terminal crashes on systems using older CP1252/ASCII character mappings.

🧹 Automatic Dependency-Free Dotenv

Includes a built-in .env parser requiring no third-party libraries, loading configurations and keeping API keys protected.

---

🔍 Pipeline Stages — Deep Dive

Stage 1 — Grounded Research (research_agent.py)

Detail	Value
Core Client	google-genai Client
Model	gemini-2.5-flash
Grounding	Google Search tool
Output Schema	Pydantic AppResearchResult

Stage 2 — Verification Audit (verify_agent.py)

Detail	Value
Verification Sample	15 random apps across categories
First-Pass Accuracy	40.0% (missed specific enterprise limits)
Final Accuracy	100.0% (after grounded verification & audit)
Accuracy Shift	+60.0%

Stage 3 — Aggregation & Clustering (analyze_data.py)

Detail	Value
Auth Distribution	API Keys (57%), OAuth2 (57%), Tokens (29%)
Access Types	Self-Serve (75%) vs Gated (25%)
Easy Wins	75 apps (100% self-serve & buildable today)
Gated Blocker	Paid plan required (47.8%), Partner outreach (39.1%)

---

📸 Demo & Screenshots

🖥️ Full Interactive Case Study Dashboard

The fully compiled dashboard features category-wise sorting, instant search, metric cards, and responsive Chart.js data visualizations:

📊 Section-by-Section Preview

Dashboard Header & Stats	Key Patterns & Strategic Insights

Agentic Workflow Pipeline	Interactive 100-App Matrix

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• Google Gemini API key (optional - falls back to pre-researched cache if omitted)

1. Clone the Repository

git clone https://github.com/Subodh26oct/composio-api-research-agent.git
cd composio-api-research-agent

2. Set Up Virtual Environment

On Windows:

python -m venv .venv
.venv\Scripts\activate

On macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

4. Configure Key

Create a .env file in the root folder:

GEMINI_API_KEY="your-gemini-api-key-here"

5. Run the Pipeline

# Run research data extraction
python research_agent.py

# Execute verification audit
python verify_agent.py

# Generate statistics
python analyze_data.py

# Compile HTML dashboard
python build_dashboard.py

---

🛠️ Technology Stack

Layer	Technology	Purpose
Language	Python 3.10+	Core scripting
Cognitive Agent	Gemini 2.5-Flash	Search-grounded content generation
Validation	Pydantic	Structured JSON schema formatting
Aggregation	Pandas	Statistical clustering & groupings
Visual Library	Chart.js	Dynamic client-side graphs
Presentation	HTML5 / CSS3 / JavaScript	Interactive single-page case study

---

🗺️ Future Roadmap

Planned pipeline enhancements:

Priority	Feature	Description
🔴 P0	Multi-Agent Consensus	Parallel research instances voting on auth patterns to minimize hallucinations
🟠 P1	Auto-Spec Crawler	Automatically extracting OpenAPI / GraphQL specs from evidence URLs
🟡 P2	YAML Exporter	Directly generating Composio-ready integration configuration manifests
🟢 P3	Credentials Verifier	Live test integrations verifying sandbox access automatically

---

👨‍💻 Author

Subodh AI & Software Engineer

---

_{Built for the Composio AI Product Ops Intern take-home assignment.}