LangGraphAgent: Command-Line Academic Research & Latest Developments Analysis Tool

LangGraphAgent is a robust, CLI-based tool for discovering, analyzing, and synthesizing the latest research advancements and technical developments across major academic fields. It leverages modern LLMs, LangGraph, LangChain, Pydantic, a self-built keyless webcrawl module for academic search/scraping, and a small router that automatically picks the right agent for each query.

Sample Output

advance-agent — deterministic, structured rendering (bold titles, dim metadata, clickable links):

simple-agent — markdown-rendered free-text answer, reached here via the router's fallback (a query without a clean field/subtopic split):

Features

• Academic Research Discovery: Query recent advancements by "Field, Subtopic" (e.g., Machine Learning, Image Processing).
• Automatic Routing: A unified entry point picks the best-fit agent per query and tells you which one it chose and why.
• LLM-Powered Extraction: Uses OpenAI models for extracting structured research details and synthesizing trends, grounded by explicit source citation rather than free-text matching (see "Design Notes" below).
• Keyless Academic Search & Scraping: webcrawl queries arXiv, Semantic Scholar, and CrossRef in parallel (no API key required) and falls back to lightweight page scraping (httpx + trafilatura) for blogs and code repositories, with per-source rate limiting to stay within each API's courtesy limits.
• Adaptive Retry: If an initial search comes back empty, advance-agent automatically broadens the query and retries once before continuing.
• LangGraph Workflows: Modular, robust pipelines for multi-step research analysis.
• Pydantic Models: Ensures type-safe, structured outputs for all research data.
• Error Handling & Logging: Defensive, user-friendly CLI with clear, accumulating error reporting — nothing gets silently overwritten between pipeline steps.

How It Works

LangGraphAgent ships two agents built on very different architectures, plus a router that picks between them.

advance-agent

• Explicit, Modular Workflow: Uses LangGraph to orchestrate a pipeline:
  1. Search Sources: Finds relevant research and technical content from arXiv, Semantic Scholar, and CrossRef.
  2. Reformulate & Retry (conditional): if the initial search comes back empty, broadens the query and searches once more before continuing (bounded to one retry).
  3. Extract Titles: Selects the most significant advancements from the numbered source list — grounded by source index, not regenerated free text, so the model can only ever cite a real source or return an empty list, never a hallucinated "title".
  4. Extract Details: Pulls structured details (authors, links, summary, etc.) for each advancement directly from its cited source, with the real source URL always guaranteed present in the output.
  5. Synthesize: Summarizes trends and future directions.
• Manual Routing: Each step is explicitly managed, ensuring robust error handling and transparency.
• Best for: Narrow, well-specified "Field, Subtopic" queries where you want reliability, traceability, and detailed logs.

simple-agent

• Dynamic, LLM-Driven Workflow: The LLM decides which webcrawl tool to use (search or scrape) at each step.
• Minimal Routing: The agent is given only the LLM and two direct LangChain tools (search_academic_sources, scrape_page) backed by webcrawl; workflow is determined on-the-fly.
• Best for: Broad, open-ended, or multi-part questions that don't map onto a single field+subtopic.

Automatic Routing

main.py at the repo root routes each query to whichever of the two agents above fits it best, so you don't have to choose manually:

uv run main.py

Routing is two-tier (router/service.py):

1. A free heuristic first checks whether the query cleanly parses as "Field, Subtopic" (or "Field -> Subtopic") — if so, it goes straight to advance-agent, no API call.
2. Anything more open-ended or ambiguous falls back to a small gpt-4o-mini classifier that picks between the two agents based on their actual strengths.

This design was validated in experiments/routing_experiment.py before being built for real — that script runs 10 fixed test queries spanning low-to-high ambiguity through the same prompt this router uses, so it doubles as a regression check for routing quality. main.py also has a safety net: if the LLM classifier ever picks advance-agent for a query that doesn't actually have a field/subtopic split, it's automatically redirected to simple-agent instead, since advance-agent can't function correctly without that structure.

Every response tells you which agent handled it and why:

Routed to advance-agent (free heuristic match)
   Reason: Query cleanly parses as field='Physics', subtopic='Quantum Computing'.

This is an additional way to reach either agent, not a replacement — both remain fully usable on their own (see Usage below), and the router only decides which one handles a given query, without changing how either one works internally.

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/LangGraphAgent.git
   cd LangGraphAgent

2. Install uv:

   # On Windows, Mac, or Linux (see uv docs for details)
   pip install uv

3. Sync dependencies:

   uv sync

4. Set up environment variables:
   • Create a single .env file at the repo root (all entry points — main.py, advance-agent/main.py, simple-agent/main.py, and experiments/routing_experiment.py — read from this one file):

     OPENAI_API_KEY=your_openai_key
     CONTACT_EMAIL=you@example.com
     SEMANTIC_SCHOLAR_API_KEY=

   • CONTACT_EMAIL is used as a courtesy identifier for arXiv and CrossRef (no signup needed).
   • SEMANTIC_SCHOLAR_API_KEY is optional — leave it blank to query keyless at a lower rate limit, or request one at https://www.semanticscholar.org/product/api for higher limits.

Usage

Unified entry point (recommended)

uv run main.py

Routes each query to advance-agent or simple-agent automatically, and prints which agent it picked — see "Automatic Routing" above.

Direct/independent access

cd advance-agent
uv run main.py

cd simple-agent
uv run main.py

Both work exactly as if the router didn't exist — useful when you already know which agent you want.

Follow the CLI prompts to enter your research query. For best results with advance-agent (directly or via the router), use clear, specific Field, Subtopic queries.

Project Structure

LangGraphAgent/
├── main.py               # Unified entry point (routes to one of the two agents below)
├── cli/                   # Shared rich theme, logging, and result rendering
├── router/                # Two-tier routing logic (heuristic + gpt-4o-mini fallback)
├── webcrawl/               # Keyless search (arXiv/Semantic Scholar/CrossRef) + scraping, shared by both agents
├── advance-agent/          # Deterministic LangGraph pipeline (also runnable standalone)
│   └── src/                # workflow.py, models.py, prompts.py
├── simple-agent/           # Dynamic ReAct agent (also runnable standalone)
├── experiments/            # routing_experiment.py - validates the router's prompt against 10 fixed test queries
└── .env                    # Single shared config for all entry points (see Installation)

Design Notes & Known Limitations

• Source grounding: advance-agent's title-extraction step is given an explicitly numbered list of sources and must cite a source_index for every advancement it selects — it cannot invent a title unconnected to a real source, and an empty list is a valid, expected answer when nothing is confidently relevant. Detail extraction then looks up that exact source by index (no fuzzy string matching), and the real source URL is always force-included in the output regardless of what the model chose to return.
• No hard topic filter: queries outside academic/STEM subjects are not rejected — they're routed and answered as best-effort rather than blocked, since CrossRef alone already spans humanities/social-science journals and a hard filter would need either a fragile keyword list or an extra LLM call for uncertain benefit.
• Result volume vs. rate limits: webcrawl fetches up to 10 total results per query (~5 per source across arXiv/Semantic Scholar/CrossRef, searched in parallel). This is a deliberate ceiling — the LLM steps only need enough sources to pick the top 5-10 advancements anyway, and Semantic Scholar's keyless public pool has already been observed to 429 under repeated rapid queries; a higher ceiling would increase exposure to that limit without a proportional quality gain. Each source has its own rate limiter (arXiv/Semantic Scholar: 3s, CrossRef: 1s) so one source's cooldown never blocks the others.

Technologies Used

• LangGraph: Graph-based workflow orchestration for LLMs.
• LangChain: LLM application framework.
• Pydantic: Data validation and settings management.
• rich: Terminal styling, markdown rendering, and logging.
• webcrawl (this repo): Keyless academic search and page scraping.
• router (this repo): Two-tier query routing.
• OpenAI: LLMs for extraction, synthesis, and routing.