{"id":51459595,"url":"https://github.com/vectorleap-pulse/portfolio-research-agent","last_synced_at":"2026-07-06T04:01:46.854Z","repository":{"id":356739624,"uuid":"1233871768","full_name":"vectorleap-pulse/portfolio-research-agent","owner":"vectorleap-pulse","description":"A full-stack web application where a user submits a research question and a multi-agent system autonomously plans, searches, retrieves, summarizes, and synthesizes a structured report - with every agent step streamed live to a unique terminal-meets-dashboard UI.","archived":false,"fork":false,"pushed_at":"2026-05-09T19:53:22.000Z","size":8692,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T21:39:40.914Z","etag":null,"topics":["agentic-ai","fastapi","full-stack","fullstack","langchain","langgraph","multi-agent","nextjs","portfolio","python","qdrant","research-agent","typescript"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vectorleap-pulse.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-09T13:13:05.000Z","updated_at":"2026-05-09T19:53:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vectorleap-pulse/portfolio-research-agent","commit_stats":null,"previous_names":["alpha5611331/portfolio-research-agent","vectorleap-pulse/portfolio-research-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/vectorleap-pulse/portfolio-research-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorleap-pulse%2Fportfolio-research-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorleap-pulse%2Fportfolio-research-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorleap-pulse%2Fportfolio-research-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorleap-pulse%2Fportfolio-research-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vectorleap-pulse","download_url":"https://codeload.github.com/vectorleap-pulse/portfolio-research-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vectorleap-pulse%2Fportfolio-research-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35177220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"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":["agentic-ai","fastapi","full-stack","fullstack","langchain","langgraph","multi-agent","nextjs","portfolio","python","qdrant","research-agent","typescript"],"created_at":"2026-07-06T04:01:46.199Z","updated_at":"2026-07-06T04:01:46.846Z","avatar_url":"https://github.com/vectorleap-pulse.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Research Command Center\n\n## Elevator Pitch\n\nA full-stack web application where a user submits a research question and a multi-agent system autonomously plans, searches, retrieves, summarizes, and synthesizes a structured report - with every agent step streamed live to a unique terminal-meets-dashboard UI.\n\n![Demo](images/demo.gif)\n\n**Demo query:**\n\n\u003e \"What is the future of AI agents in healthcare?\"\n\n---\n\n## Repositories\n\n|             | Link                                                                                                |\n| ----------- | --------------------------------------------------------------------------------------------------- |\n| Main (this) | [portfolio-research-agent](https://github.com/vectorleap-pulse/portfolio-research-agent)                   |\n| Backend     | [portfolio-research-agent-backend](https://github.com/vectorleap-pulse/portfolio-research-agent-backend)   |\n| Frontend    | [portfolio-research-agent-frontend](https://github.com/vectorleap-pulse/portfolio-research-agent-frontend) |\n\n---\n\n## Portfolio Goals\n\nThis project is designed to demonstrate the following skills simultaneously:\n\n| Domain          | Skills Demonstrated                                                         |\n| --------------- | --------------------------------------------------------------------------- |\n| Agentic AI      | LangGraph StateGraph, multi-agent orchestration, tool use, streaming events |\n| Backend         | FastAPI, async Python, WebSocket streaming, REST API design                 |\n| Frontend        | Next.js 14 App Router, TypeScript, real-time UI, state management           |\n| LLM integration | OpenAI SDK-compatible (OpenAI + Groq), prompt engineering, streaming        |\n| Search          | Tavily API (free tier), result ranking and deduplication                    |\n| UI/UX           | Unique dark command-center design, live agent trace visualization           |\n| DevOps          | Docker Compose, environment config,`.env` management                      |\n\n---\n\n## System Architecture\n\n```\nUser Query\n    │\n    ▼\n┌──────────────┐      WebSocket / SSE      ┌──────────────────────────┐\n│   Next.js    │◄─────────────────────────►│       FastAPI            │\n│  Frontend    │                           │                          │\n│              │   REST (submit query)     │  ┌────────────────────┐  │\n│  Command Bar │──────────────────────────►│  │  Agent Orchestrator│  │\n│  Agent Trace │                           │  │   (LangGraph)      │  │\n│  Log Stream  │◄── real-time event stream─│  └────────┬───────────┘  │\n│  Report View │                           │           │              │\n│  Sources     │                           │  ┌────────▼───────────┐  │\n└──────────────┘                           │  │   Planner Agent    │  │\n                                           │  │  (breaks subtopics)│  │\n                                           │  └────────┬───────────┘  │\n                                           │           │              │\n                                           │  ┌────────▼───────────┐  │\n                                           │  │  Researcher Agents │  │\n                                           │  │  (parallel per     │  │\n                                           │  │   subtopic)        │  │\n                                           │  │  ┌──────────────┐  │  │\n                                           │  │  │ Tavily Search│  │  │\n                                           │  │  └──────────────┘  │  │\n                                           │  └────────┬───────────┘  │\n                                           │           │              │\n                                           │  ┌────────▼───────────┐  │\n                                           │  │  Summarizer Agent  │  │\n                                           │  └────────┬───────────┘  │\n                                           │           │              │\n                                           │  ┌────────▼───────────┐  │\n                                           │  │ Synthesizer Agent  │  │\n                                           │  │ (final report)     │  │\n                                           │  └────────────────────┘  │\n                                           │                          │\n                                           │  OpenAI / Groq SDK       │\n                                           └──────────────────────────┘\n```\n\n---\n\n## Agentic Framework - LangGraph\n\nThe entire agent pipeline is a **LangGraph `StateGraph`**. Each agent is a typed node; edges and conditional routing define execution order. This makes the pipeline inspectable, serializable, and easy to extend without touching orchestration logic.\n\n### Why LangGraph\n\n- **Explicit graph topology** - the planner → researchers → summarizer → synthesizer flow is declared as nodes and edges, not implicit function calls; the graph is the architecture\n- **Native parallel fan-out** - LangGraph's `Send` API dynamically spawns one Researcher node per subtopic; results are merged back into shared state automatically via a reducer\n- **Built-in streaming** - `.astream_events()` emits granular events for every node entry, node exit, and LLM token; the FastAPI WebSocket handler maps these directly to the frontend event schema with no manual event management\n- **State as single source of truth** - a typed `ResearchState` dict flows through the graph carrying query, provider, model, subtopics, sources, summaries, and final report; no hidden side-channels\n\n### Graph Topology\n\n```\nSTART → planner → [Send × N subtopics] → researcher (×N, parallel)\n                                              ↓ (merge)\n                                          summarizer\n                                              ↓\n                                          synthesizer → END\n```\n\n### Tools (used inside Researcher node)\n\nEach Researcher node binds a LangChain tool to its LLM and runs a tool-calling loop until sources are collected:\n\n- `tavily_search` - web search via Tavily API\n\n### LLM Inside Nodes\n\nEvery node reads `provider` and `model` from the shared state and constructs a `ChatOpenAI` client (from `langchain-openai`) on the fly. For Groq, the same class is used with `base_url` pointed at Groq's OpenAI-compatible endpoint - no separate code path for each provider.\n\n### Streaming to Frontend\n\nLangGraph's `.astream_events()` output is consumed by the FastAPI WebSocket handler, which translates each LangGraph event kind into the typed frontend event schema (`PLAN_CREATED`, `SEARCH_DONE`, `SUMMARY_CHUNK`, etc.) before broadcasting over the WebSocket connection.\n\n---\n\n## Backend - FastAPI (Python)\n\n### Agent Pipeline\n\nFour LangGraph nodes run in sequence; Researcher nodes fan out in parallel via `Send`.\n\n#### 1. Planner Agent\n\n- Input: raw user query\n- Output: list of 3–5 subtopics with search strategies\n- LLM call with structured output (JSON mode)\n- Emits `PLAN_CREATED` event\n\n#### 2. Researcher Agent (parallel, one per subtopic)\n\n- **Tavily web search**: fetches top 5 results per subtopic (free tier)\n- Deduplicates results by URL\n- Emits `SEARCH_DONE`, `SOURCES_COLLECTED` events per subtopic\n\n#### 3. Summarizer Agent\n\n- Summarizes each subtopic's collected sources into a concise section\n- Streams partial tokens to frontend\n- Emits `SUMMARY_CHUNK` (streaming) and `SUMMARY_DONE` events\n\n#### 4. Synthesizer Agent\n\n- Merges all subtopic summaries into a final structured report\n- Sections: Executive Summary, Key Findings, Detailed Analysis, Citations\n- Streams final report tokens to frontend\n- Emits `REPORT_CHUNK` (streaming) and `REPORT_DONE` events\n\n### LLM Configuration\n\nUses **OpenAI Python SDK** - compatible with both providers:\n\n```python\n# OpenAI\nclient = openai.AsyncOpenAI(api_key=OPENAI_API_KEY)\n\n# Groq (OpenAI-compatible endpoint)\nclient = openai.AsyncOpenAI(\n    api_key=GROQ_API_KEY,\n    base_url=\"https://api.groq.com/openai/v1\"\n)\n```\n\nUser selects provider + model from the UI. Backend reads selection from request payload.\n\nSupported models:\n\n- `gpt-4o-mini` / `gpt-4o` (OpenAI)\n- `llama-3.3-70b-versatile` / `llama-3.1-8b-instant` (Groq)\n\n### API Endpoints\n\n```\nPOST   /api/research          Submit query → returns session_id\nGET    /api/research/{id}     Get full session result\nGET    /api/sessions          List past sessions\nDELETE /api/sessions/{id}     Delete session\n\nWS     /ws/{session_id}       Real-time agent event stream\n```\n\n### Event Stream Schema\n\nEvery WebSocket message is a typed JSON event:\n\n```json\n{\n  \"event\": \"PLAN_CREATED | SEARCH_DONE | SOURCES_COLLECTED | SUMMARY_CHUNK | SUMMARY_DONE | REPORT_CHUNK | REPORT_DONE | ERROR\",\n  \"session_id\": \"uuid\",\n  \"timestamp\": \"ISO-8601\",\n  \"agent\": \"planner | researcher | summarizer | synthesizer\",\n  \"subtopic\": \"optional string\",\n  \"data\": {}\n}\n```\n\n### Tech Stack\n\n- Python 3.11+\n- FastAPI + Uvicorn\n- LangGraph - agent graph definition, parallel `Send`, state management, `.astream_events()` streaming\n- `langchain-openai` - `ChatOpenAI` wrapping OpenAI SDK; Groq via `base_url` override\n- `langchain-core` - `@tool` decorator for Tavily tool\n- `tavily-python` client\n- Pydantic v2 for request/response schemas\n- `python-dotenv`\n\n---\n\n## Frontend - Next.js 14\n\n### Design Language: \"Research Command Center\"\n\n**Not** a standard chat UI. Inspired by:\n\n- IDE terminals (VS Code, Warp)\n- Mission control dashboards\n- Hacker-aesthetic meets editorial\n\n**Visual identity:**\n\n- Dark base: `#0a0a0f` (near-black with blue undertone)\n- Accent: electric indigo `#6366f1` + cyan `#06b6d4`\n- Monospace font for log streams and agent traces (JetBrains Mono)\n- Serif font for the final report (Playfair Display)\n- Subtle animated grid background (CSS only, no canvas)\n- Glassmorphism cards with `backdrop-blur` for panels\n- Framer Motion for agent node animations and transitions\n\n### Layout\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  HEADER: logo + provider selector (OpenAI / Groq) + model pick  │\n├─────────────────────────────────────────────────────────────────┤\n│  COMMAND BAR: full-width query input (VS Code palette style)    │\n│               [Enter to Research \u003e\u003e]                            │\n├──────────────┬──────────────────────────┬───────────────────────┤\n│              │                          │                       │\n│  AGENT TRACE │   LIVE LOG STREAM        │   SOURCES PANEL       │\n│  (left 20%)  │   (center 50%)           │   (right 30%)         │\n│              │                          │                       │\n│  Visual tree │  Timestamped log lines   │  Source cards:        │\n│  of agents   │  with color-coded        │  - title              │\n│  and their   │  event types             │  - domain badge       │\n│  status:     │                          │  - relevance score    │\n│              │  ● PLAN_CREATED          │  - snippet            │\n│  ○ Planner   │  ● SEARCH: subtopic 1    │  - [open link]        │\n│  ├○ Research │  ● SEARCH: subtopic 2    │                       │\n│  ├○ Research │  ● SUMMARY streaming...  │  Expandable per       │\n│  └○ Synthsz  │  ● REPORT streaming...   │  subtopic             │\n│              │                          │                       │\n├──────────────┴──────────────────────────┴───────────────────────┤\n│  REPORT PANEL (collapsible, expands below on REPORT_DONE)       │\n│  Structured markdown report with section headers, citations     │\n│  [Copy] [Export MD] [New Research]                              │\n├─────────────────────────────────────────────────────────────────┤\n│  SESSION HISTORY (collapsible bottom drawer)                    │\n│  Past queries with timestamps - click to reload                 │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Component Breakdown\n\n| Component            | Description                                                                |\n| -------------------- | -------------------------------------------------------------------------- |\n| `CommandBar`       | Full-width input with animated placeholder cycling through example queries |\n| `ProviderSelector` | Dropdown to pick OpenAI or Groq + model within each                        |\n| `AgentTraceTree`   | Animated vertical tree, nodes pulse when active, checkmark on done         |\n| `LogStream`        | Auto-scrolling terminal-style log with color per event type                |\n| `SourcesPanel`     | Tabbed by subtopic, cards with favicon, domain badge, score bar            |\n| `ReportViewer`     | Streaming markdown renderer, serif font, section anchors, TOC              |\n| `SessionDrawer`    | Bottom slide-up list of past sessions from `/api/sessions`               |\n| `StatusBar`        | Footer: current agent, token count, latency                                |\n\n### Real-time Streaming\n\n- WebSocket connection opened immediately on query submit\n- `LogStream` appends each event as a formatted line\n- `ReportViewer` renders tokens incrementally as `REPORT_CHUNK` events arrive\n- Agent nodes in `AgentTraceTree` transition: `idle → active → done → error`\n\n### State Management\n\n- Zustand store: `useResearchStore`\n  - `session`, `events[]`, `sources[]`, `reportChunks[]`, `agentStatuses{}`\n- No Redux, no prop drilling\n\n### Tech Stack\n\n- Next.js 14 (App Router, TypeScript)\n- Tailwind CSS + custom design tokens\n- Framer Motion (agent tree animations, panel transitions)\n- Zustand (state)\n- `react-markdown` + `remark-gfm` (report rendering)\n- JetBrains Mono + Playfair Display (Google Fonts)\n- `date-fns` (log timestamps)\n\n---\n\n## Environment Variables\n\n```env\n# Backend (.env)\nOPENAI_API_KEY=sk-...\nGROQ_API_KEY=gsk_...\nTAVILY_API_KEY=tvly-...\nDEFAULT_LLM_PROVIDER=openai\nDEFAULT_MODEL=gpt-4o-mini\n\n# Frontend (.env.local)\nNEXT_PUBLIC_API_URL=http://localhost:8000\nNEXT_PUBLIC_WS_URL=ws://localhost:8000\n```\n\n---\n\n## Project Structure\n\n```\n1.research-agent/\n├── backend/\n│   ├── main.py                  # FastAPI app, WebSocket handler, event translator\n│   ├── graph.py                 # LangGraph StateGraph definition and compilation\n│   ├── state.py                 # ResearchState TypedDict\n│   ├── agents/\n│   │   ├── planner.py           # LangGraph node: plan subtopics\n│   │   ├── researcher.py        # LangGraph node: tool-calling loop (Tavily)\n│   │   ├── summarizer.py        # LangGraph node: per-subtopic summary\n│   │   └── synthesizer.py       # LangGraph node: final report\n│   ├── tools/\n│   │   └── tavily_search.py     # @tool: Tavily web search\n│   ├── models/\n│   │   └── schemas.py           # Pydantic request/response models\n│   ├── services/\n│   │   └── llm.py               # ChatOpenAI factory (OpenAI + Groq via base_url)\n│   └── requirements.txt\n├── frontend/\n│   ├── app/\n│   │   ├── layout.tsx\n│   │   ├── page.tsx             # Main research page\n│   │   └── api/                 # Next.js route handlers (proxy)\n│   ├── components/\n│   │   ├── CommandBar.tsx\n│   │   ├── ProviderSelector.tsx\n│   │   ├── AgentTraceTree.tsx\n│   │   ├── LogStream.tsx\n│   │   ├── SourcesPanel.tsx\n│   │   ├── ReportViewer.tsx\n│   │   ├── SessionDrawer.tsx\n│   │   └── StatusBar.tsx\n│   ├── store/\n│   │   └── useResearchStore.ts\n│   ├── types/\n│   │   └── events.ts\n│   └── package.json\n├── docker-compose.yml           # backend + frontend\n└── workspace.md\n```\n\n---\n\n## Scope Notes\n\n- **No authentication** - this is a portfolio demo; any user can submit a query and view past sessions. No login, no user isolation.\n\n---\n\n## Why This Is Strong as a Portfolio Project\n\n1. **Real agentic framework** - uses LangGraph `StateGraph` with typed state, conditional fan-out via `Send`, and built-in streaming; not a hand-rolled loop or \"LangGraph-style\" approximation\n2. **Multi-agent system** - planner → parallel researchers → summarizer → synthesizer; each is a discrete node with a single responsibility\n3. **Real full-stack** - async FastAPI backend, React frontend, WebSocket streaming, external APIs\n4. **Provider flexibility** - `ChatOpenAI` from `langchain-openai` used as a universal interface; Groq swapped in via `base_url` with zero extra code\n5. **Live observability** - LangGraph's `.astream_events()` feeds every node transition and LLM token to the UI in real time; nothing hidden\n6. **Unique UI** - command-center design, not a generic chat template; shows frontend design skill alongside AI skill\n7. **Free-tier viable** - Tavily free tier + Groq free tier means it runs at zero cost for demos\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvectorleap-pulse%2Fportfolio-research-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvectorleap-pulse%2Fportfolio-research-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvectorleap-pulse%2Fportfolio-research-agent/lists"}