Stop Chunking Documents Blindly: Agentic File Search Exposed

Stop Chunking Documents Blindly: Agentic File Search Exposed

What if everything you believe about document search is fundamentally broken?

You've spent months fine-tuning your RAG pipeline. Perfect chunk sizes, optimal overlap, bleeding-edge embedding models. Yet your system still chokes when someone asks, "What's the adjusted purchase price after escrow in Exhibit B?" The answer exists in your documents—right there, plain as day—but your chunks are blind to it. Cross-references become meaningless tokens. Logical connections dissolve into semantic noise. Your "intelligent" system is actually dumber than a first-year law clerk with a highlighter.

This isn't a hypothetical failure. It's the dirty secret of traditional Retrieval-Augmented Generation: chunks lose context, cross-references become invisible, and similarity absolutely does not equal relevance. Every time you split a document, you're committing an act of intellectual vandalism. You're shredding the very relationships that make information meaningful.

But what if your AI could search like a human actually does?

Enter agentic-file-search—a radical reimagining of document exploration that doesn't destroy documents to understand them. Instead of pre-computing embeddings and praying for semantic luck, this agent dynamically navigates files through reasoning, cross-references, and strategic backtracking. It scans, it thinks, it follows breadcrumbs. And it's about to make your chunk-based RAG look like a stone-age tool.

Ready to see what you've been missing?

What is agentic-file-search?

agentic-file-search is an AI-powered document search agent created by PromtEngineer that explores files through human-like reasoning rather than destructive preprocessing. Built upon the foundation of run-llama/fs-explorer, this open-source project represents a paradigm shift in how AI systems interact with document collections.

The repository has been gaining serious traction among developers frustrated with traditional RAG limitations. Its core thesis is deceptively simple: documents are structured for human navigation, so AI should navigate them like humans do. Instead of treating a 50-page legal contract as 200 isolated text chunks, agentic-file-search preserves the document's inherent topology—sections, subsections, exhibits, cross-references, and all.

The project leverages Google Gemini 3 Flash as its reasoning engine, outputting structured JSON that drives a sophisticated three-phase exploration strategy. Document parsing happens locally through Docling, an open-source parser supporting PDF, DOCX, PPTX, XLSX, HTML, and Markdown^{↗ Smart Converter} formats. Orchestration is handled by LlamaIndex Workflows, providing an event-driven architecture that coordinates the agent's decision-making with file system operations.

What makes this tool genuinely exciting isn't just its architecture—it's the economics. At approximately $0.001 per query with full token tracking, it demolishes the cost barriers that make enterprise RAG deployments so painful. The included web interface streams execution steps in real-time via WebSocket, transforming opaque AI reasoning into transparent, auditable process.

For developers building document-heavy applications—legal tech, financial analysis, compliance, research—this isn't merely an alternative. It's an escape hatch from the chunking trap.

Key Features That Destroy Traditional RAG

The feature set of agentic-file-search reveals how deeply its creators understand document search failures. Each capability directly addresses a specific RAG limitation:

Six Specialized File Tools

The agent wields a surgical toolkit rather than a semantic bludgeon:

• scan_folder — Parallel preview of entire directories, establishing strategic overview
• preview_file — Rapid content sampling without full extraction
• parse_file — Deep document parsing via Docling for complex formats
• read — Targeted content extraction from specific locations
• grep — Pattern-based search for precise term location
• glob — File pattern matching for systematic exploration

This isn't a generic search API. It's a deliberate reasoning toolkit where each tool selection reflects strategic intent.

Multi-Format Document Intelligence

Through Docling integration, the system handles PDF, DOCX, PPTX, XLSX, HTML, and Markdown locally. No cloud document processing. No format-dependent failures. The parser preserves structural elements—tables, headers, lists—that chunking typically destroys.

Structured JSON Reasoning with Gemini 3 Flash

Google's Gemini 3 Flash doesn't generate free-text responses that require fragile parsing. It outputs structured JSON representing tool selections, parameters, and reasoning chains. This structured approach eliminates hallucinated tool calls and enables precise execution tracking.

Real-Time WebSocket Streaming Interface

The web UI doesn't just display results—it reveals cognition. Watch the agent scan, deliberate, dive deep, and backtrack. Every step streams live. For debugging, trust-building, and system refinement, this transparency is invaluable.

Citations and Token Economics

Every answer includes source references pointing to specific documents and locations. Token usage and cost statistics display automatically. At roughly one-tenth of a cent per query, you can finally build document AI that won't trigger finance department panic attacks.

Use Cases Where agentic-file-search Dominates

The test document sets included in the repository reveal where this approach shines. These aren't toy examples—they're realistic scenarios where traditional RAG fails catastrophically.

Legal Document Analysis with Cross-References

The data/test_acquisition/ directory contains 10 interconnected legal documents typical of M&A due diligence. Purchase agreements reference exhibits. Exhibits reference schedules. Schedules reference corporate bylaws. Ask "What is the adjusted purchase price?" and the answer requires following a chain of cross-references across multiple documents. Chunk-based RAG sees each reference as meaningless text. The agent follows them deliberately.

Multi-Document Financial Synthesis

The data/large_acquisition/ set contains 25 documents with extensive cross-references. Queries like "What are all the financial terms including adjustments and escrow?" or "What happens to employees after the acquisition?" require synthesizing information from employment agreements, purchase terms, and disclosure schedules—then connecting related provisions across document boundaries.

Regulatory Compliance Verification

Compliance officers need to verify that policies across hundreds of documents remain consistent. When regulation 47-CFR-15.247 references test procedure KDB 558074 D01, a chunking system might retrieve both documents independently without recognizing their dependency. The agentic approach explicitly follows the reference chain, ensuring complete verification.

Technical Documentation Navigation

Software documentation is notoriously cross-referenced: "See configuration guide section 4.2 for database setup requirements." Traditional search returns the referencing page and the referenced page as separate, unconnected results. The agent understands the navigation instruction and executes it, delivering integrated answers rather than fragmented references.

Step-by-Step Installation & Setup Guide

Getting agentic-file-search running takes minutes, not hours. The project uses uv for blazing-fast Python^{↗ Bright Coding Blog} package management, though standard pip works equally well.

Prerequisites

• Python 3.10+
• uv installed (recommended) or pip
• Google AI Studio API key

Clone and Install

# Clone the repository
git clone https://github.com/PromtEngineer/agentic-file-search.git
cd agentic-file-search

# Install with uv (recommended for speed)
uv pip install .

# Alternative: standard pip installation
pip install .

The uv approach is strongly recommended—dependency resolution completes in seconds rather than minutes, and virtual environment management becomes transparent.

API Key Configuration

Create a .env file in the project root:

GOOGLE_API_KEY=your_api_key_here

Obtain your key from Google AI Studio. The free tier provides generous quotas sufficient for extensive testing.

Development Environment (Optional)

For contributors or those extending the system:

# Install with development dependencies
uv pip install -e ".[dev]"

# Verify installation
uv run pytest

# Code quality check
uv run ruff check .

Launch Web Interface

# Start the FastAPI server with WebSocket support
uv run uvicorn fs_explorer.server:app --host 127.0.0.1 --port 8000

Navigate to http://127.0.0.1:8000 to access the single-file web interface. No build step, no npm dependencies, no configuration files—just instant functionality.

REAL Code Examples from the Repository

The repository's README contains concrete implementation patterns that demonstrate the system's design philosophy. Let's examine them with detailed technical commentary.

Example 1: Basic CLI Query Execution

The simplest entry point reveals the agent's core interaction pattern:

# Basic query against test acquisition documents
uv run explore --task "What is the purchase price in data/test_acquisition/?"

What's happening under the hood? The explore command (defined in main.py using Typer) initializes the workflow engine, which constructs a task context including the target directory. The agent receives this as its objective and begins the three-phase strategy: scanning data/test_acquisition/ for document overview, previewing promising files, then parsing deeply when purchase price indicators appear. The uv run prefix ensures execution within the project's managed environment without explicit virtualenv activation.

Example 2: Multi-Document Complex Query

This example demonstrates the system's strength with cross-document synthesis:

# Complex financial terms query spanning multiple documents
uv run explore --task "Look in data/large_acquisition/. What are all the financial terms including adjustments and escrow?"

Technical significance: The explicit directory prefix "Look in data/large_acquisition/." isn't mere politeness—it's task framing that constrains the agent's initial scan_folder scope. The query components "financial terms," "adjustments," and "escrow" provide multiple semantic anchors for the preview phase. Critically, "including adjustments and escrow" signals to the reasoning engine that these aren't separate queries but interconnected financial provisions that must be co-reported. The agent will likely: scan the 25-document directory, preview documents with financial indicators (purchase agreement, disclosure schedules, escrow agreement), parse relevant files fully, then backtrack to follow cross-references between these documents.

Example 3: Cross-Reference Chain Navigation

This is where agentic-file-search fundamentally diverges from RAG:

# Query requiring explicit cross-reference following
uv run explore --task "Look in data/test_acquisition/. What is the adjusted purchase price?"

Why traditional RAG fails here: The "adjusted purchase price" rarely appears as a literal phrase in the primary purchase agreement. Instead, the agreement states: "Purchase Price: $10,000,000, subject to adjustments per Section 2.3 and Exhibit C." Section 2.3 references working capital calculations. Exhibit C references the closing balance sheet. The adjustment itself is computed across three documents. Chunk-based systems might retrieve the $10,000,000 figure or isolated adjustment clauses, but they cannot execute the computational chain the agent performs: reading Section 2.3, identifying the adjustment formula, locating Exhibit C's values, and computing the final adjusted amount.

Example 4: Web Server Launch for Real-Time Monitoring

# Start WebSocket-enabled FastAPI server
uv run uvicorn fs_explorer.server:app --host 127.0.0.1 --port 8000

Architecture insight: This single command launches the complete web interface stack. The server.py module (per project structure) implements FastAPI with native WebSocket support. Unlike polling-based interfaces, WebSocket enables true streaming of agent reasoning steps—each tool selection, each file access, each backtrack decision flows to the browser in real-time. The ui.html single-file design eliminates build complexity while providing: folder browser for target selection, step-by-step execution log visualization, final answer rendering with citations, and token/cost statistics dashboard.

Example 5: Employee Impact Synthesis Query

# Multi-document synthesis requiring contextual reasoning
uv run explore --task "Look in data/large_acquisition/. What happens to employees after the acquisition?"

Advanced pattern recognition: This query exemplifies distributed information synthesis. Employee outcomes aren't typically consolidated in one document—they're scattered across: employment agreements (retention terms), purchase agreement (employee transfer provisions), benefit plans (continuation rights), and possibly separate transition services agreements. The agent must recognize that "what happens to employees" is a thematic query requiring aggregation across document types, not a keyword search. It will likely employ grep for employee-related terms, preview_file on HR-related documents, deep parse_file on employment provisions, and potentially glob for related agreement patterns like *employment*, *benefit*, *transition*.

Advanced Usage & Best Practices

Optimize Query Framing

The agent's reasoning quality depends heavily on task specificity. "Find information about the deal" yields worse results than "Identify all closing conditions in the purchase agreement and their current status." Explicit document type references ("purchase agreement," "disclosure schedule") help the preview phase prioritize correctly.

Leverage Directory Structure

Organize documents with consistent naming conventions. The glob tool uses patterns—data/2024-Q1-*/*.pdf enables efficient scoped exploration. Nested directories with semantic naming accelerate scan_folder relevance ranking.

Monitor Token Patterns

With $0.001/query average costs, most use cases are economically trivial. However, complex multi-document queries with extensive backtracking can accumulate. The web UI's token tracking reveals cost drivers—use this data to optimize frequently-executed query patterns.

Extend the Tool Suite

The six-tool architecture in fs.py is intentionally modular. Custom tools for domain-specific operations (database schema introspection, API endpoint discovery) integrate naturally into the LlamaIndex workflow. The Pydantic models in models.py enforce structured tool interfaces.

Production Deployment Considerations

The included server runs single-threaded for development. For production, deploy behind a reverse proxy with Uvicorn workers: uvicorn fs_explorer.server:app --workers 4. Consider Redis for session state if scaling beyond single-server deployments.

Comparison with Alternatives

The verdict: Traditional RAG excels at semantic similarity search across massive, homogeneous text corpora where exact relationships matter less than thematic relevance. agentic-file-search dominates when document structure carries meaning, cross-references are critical, and reasoning transparency is required. For legal, financial, compliance, and technical documentation use cases, the choice is increasingly clear.

FAQ: Developer Concerns Answered

Q: Does agentic-file-search replace my existing RAG pipeline entirely? A: Not necessarily—it's optimized for structured document exploration where relationships matter. For broad semantic search across millions of unstructured documents, traditional embedding-based retrieval may still serve. Consider hybrid architectures: agentic search for deep document analysis, RAG for initial candidate retrieval.

Q: How does it handle documents with hundreds of cross-references? A: The backtracking phase maintains a visited-document registry to prevent infinite loops. The LlamaIndex workflow engine manages state across exploration steps, with configurable depth limits for pathological reference chains.

Q: Is my document data sent to Google? A: Document parsing occurs locally via Docling. Only selected text excerpts are transmitted to Gemini for reasoning. For sensitive documents, review Google's AI Studio data handling policies and consider enterprise Gemini deployments with enhanced privacy guarantees.

Q: Can I use a different LLM provider? A: The agent.py module encapsulates Gemini client initialization. Swapping to OpenAI, Anthropic, or local models requires modifying this module's JSON structured output handling. The architecture supports provider abstraction—community contributions welcome.

Q: What's the maximum document collection size? A: Performance depends on directory breadth vs. depth. The parallel scan_folder handles hundreds of files efficiently. For thousands+ documents, consider hierarchical directory structures or pre-filtering with glob patterns. The agent reasons about file lists, not embedding indices, so scaling characteristics differ from vector databases.

Q: How accurate are the cost estimates? A: Token tracking uses Gemini's reported usage metadata. Actual billing may vary slightly based on Google AI Studio pricing updates. The $0.001/query figure reflects typical test document queries; complex multi-document explorations may reach $0.005-0.01.

Q: Can this work with cloud storage (S3, GCS, Azure Blob)? A: Currently implements local filesystem tools. Extending fs.py with cloud storage adapters is straightforward—the tool interface abstracts storage location. Community forks have demonstrated S3 integration via s3fs.

Conclusion: The Future of Document Intelligence Is Agentic

We've accepted document destruction as the price of AI search for too long. Chunking was a reasonable hack when models couldn't reason across file boundaries, when cross-references were too complex to navigate, when we had no alternative. That era is ending.

agentic-file-search demonstrates a fundamentally different path: preserve document intelligence, reason through structure, follow references deliberately. At roughly one-tenth of a cent per query, with full transparency into every decision, it delivers capabilities that million-dollar RAG deployments still struggle to achieve.

The included test sets—10 interconnected legal documents, 25-document acquisition packages—aren't just demonstrations. They're provocations. They ask: can your current system handle this? Honestly?

For developers building the next generation of legal tech, financial analysis tools, compliance platforms, and research systems, the repository at https://github.com/PromtEngineer/agentic-file-search isn't merely interesting code. It's a template for escape from the chunking trap.

Clone it. Run it. Watch the agent reason through documents in ways your embedding pipeline never could. Then ask yourself: why are you still chunking?

Star the repository, contribute extensions, and join the movement toward truly intelligent document exploration.