Example: Agentic Research Engine (Node.js)

In this tutorial, we'll build an Agentic Research tool. It uses CiteKit to navigate a library of technical papers, performing Contextual Retrieval to extract specific sections (like "Methodology") with perfect fidelity.

This demonstrates the core power of CiteKit: Providing Deterministic Evidence for high-density research agents.

Run the Complete Example

A fully implemented version of this example is available in the repository:

Location: examples/research-app/

Quick Start:

cd examples/research-app
npm install
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
mkdir papers
# Add a PDF to papers/sample_paper.pdf
npm start

See the README for full instructions.

Get the Example (Git)

git clone https://github.com/abdushakurob/citekit.git
cd citekit/examples/research-app

CLI Usage (Optional)

While this example uses the programmatic Node.js API, you can also explore with CLI commands:

JavaScript CLI:

npx citekit ingest papers/deep_research_v4.pdf document
npx citekit list  # See all ingested resources
npx citekit structure paper_id  # View structural map

Python CLI:

python -m citekit ingest papers/deep_research_v4.pdf document
python -m citekit list
python -m citekit structure paper_id

Since v0.1.8, both SDKs have full CLI parity with all 8 commands.

Why this is a "Modern" Approach

Unlike traditional systems that rely on keyword search or random text chunks, an Agentic Research workflow uses CiteKit to:

1. Understand Structure: The agent sees the "TOC" of the document first.
2. Navigate Hierarchically: It decides which section is relevant based on summaries.
3. Extract Deterministically: It pulls the exact pages, preserving all diagrams, formulas, and formatting.

Prerequisites

• Node.js 18+
• A mapper API key (Gemini by default).

1. Project Setup

mkdir citekit-research-agent
cd citekit-research-agent
npm init -y
npm install citekit dotenv

2. The Implementation

/* research_agent.js */
import 'dotenv/config';
import fs from 'node:fs';
import path from 'node:path';
import { CiteKitClient } from 'citekit';

// CiteKit acts as the "Optical" layer for our researcher
const client = new CiteKitClient({
    outputDir: 'research_evidence'
});

async function runResearchTask() {
    const paperPath = './papers/deep_research_v4.pdf';
    
    console.log(`[INFO] Inspecting Paper: ${path.basename(paperPath)}`);

    // STEP 1: Discovery (Ingestion)
    // The file is sent to the mapper service (Gemini by default) ONCE to generate the map.
    // This is the only time the file leaves your local machine.
    const map = await client.ingest(paperPath, 'document');
    
    // STEP 2: Intent Analysis
    // We want to find where the experimental methodology is.
    // In a real agent, the LLM would pick these node IDs.
    const methodologyNodes = map.nodes.filter(node => 
        node.id.includes('method') || node.summary?.includes('experimental')
    );

    // STEP 3: Contextual Retrieval & Evidence Extraction
    for (const node of methodologyNodes) {
        console.log(`[INFO] Orchestrating Context: "${node.title}"`);
        
        // This extracts the specific pages as a high-fidelity PDF slice
        const evidence = await client.resolve(map.resource_id, node.id);
        
        console.log(`[SUCCESS] Evidence extracted to: ${evidence.output_path}`);
    }
}

runResearchTask().catch(console.error);

Modern Capabilities

1. Hierarchical Navigation

By using the CiteKit Map, your agent doesn't have to "guess" where information is. It sees a recursive structure of Parts → Chapters → Sections, allowing for Zoomable Context.

2. High-Density Grounding

When the agent cites a formula or a diagram from page 14, it doesn't just quote text. It provides the Visual Evidence (the PDF slice) to the reasoning model, ensuring the most accurate grounding possible.

3. Context Orchestration

This pattern is ideal for Multi-Agent Systems. One agent (the "Map Reader") identifies the relevant nodes, and another agent (the "Verifier") receives the sliced PDF to perform deep analysis.