Core Concepts

Architecture Overview

gnaw is built on a modular architecture that combines traditional text search with AI-powered understanding:

graph TD
    A[User Query] --> B{Query Type}
    B -->|Traditional| C[Regex Engine]
    B -->|AI-Powered| D[AI Processor]
    C --> E[Search Engine]
    D --> F[Query Understanding]
    F --> E
    E --> G[Parallel Search]
    G --> H[Result Processing]
    H --> I[Format Output]

Key Components

• Search Engine: High-performance parallel search across multiple files and directories
• AI Processor: Natural language understanding and intelligent query processing
• Format Engine: Flexible output formatting (JSON, YAML, CSV, custom)
• API Server: RESTful API for integration with other tools and services

Search Modes

gnaw operates in two primary modes:

1. Traditional Search: Utilizes a highly optimized regex engine for raw speed, similar to grep.
2. AI-Powered Search: Leverages large language models (LLMs) to understand natural language queries and provide more relevant results.

Data Flow

1. Query Input: User provides a query via CLI or API.
2. Query Parsing: The system determines if the query is traditional (regex) or AI-powered (natural language).
3. Execution:
   • Traditional: Directly executed by the regex engine.
   • AI-Powered: Sent to the AI processor for understanding and conversion into an optimized search query.
4. Parallel Search: The optimized query is executed across the codebase using a parallel search engine.
5. Result Processing: Raw results are filtered, ranked, and processed.
6. Output Formatting: Results are formatted according to user-defined preferences (e.g., JSON, YAML, CSV).

This architecture ensures both speed for traditional tasks and intelligence for complex, natural language queries.