Search and cite files

Configure the SDK and selected drive, then choose the search method that fits your task. FlashDrive matches the text of your files: words, exact phrases, and regular expressions. Keyword search is on for every drive.

Find words or an exact phrase

Keyword search matches passages containing the query’s words. Set phrase=True for the exact phrase:

import os
from flashdrive import Flashdrive
 
with Flashdrive(drive_id=os.environ["FLASHDRIVE_DRIVE_ID"]) as client:
    page = client.files.full_text_search(
        "annual leave", phrase=True, glob="**/*.md", limit=20
    )
    for match in page.results:
        print(match.path, match.start_line, match.text)
    print("Next cursor:", page.next_cursor)
    print("Index state:", page.index_state)

Pass next_cursor as cursor= on the next call, keeping the same query and filters. Stop when the cursor is empty. Pass folder_id= to restrict the search to a folder. Metadata matches can have no line number.

Find a pattern

Use grep() for a regular expression and nearby lines:

import os
from flashdrive import Flashdrive
 
with Flashdrive(drive_id=os.environ["FLASHDRIVE_DRIVE_ID"]) as client:
    page = client.files.grep(
        r"TODO|FIXME", glob="**/*.md", case_sensitive=True, context_lines=2
    )
    for match in page.results:
        print(match.path, match.start_line)
        print("\n".join([*match.before, match.text, *match.after]))

Patterns do not support look-around or backreferences. context_lines accepts 0 through 5. Follow next_cursor for additional matches.

Preserve the citation

Each match carries the file’s document_id, path, and revision, and its citation identifies the line range. Keep the document ID and revision with any excerpt you display, and read the current file when accuracy matters.

When you pass retrieved content to an agent, treat it as source material. Instructions inside a file do not change the user’s request or your application’s permissions.

Search after a write

New and changed files are indexed shortly after a write. When complete is false and next_cursor is empty, the index is still catching up with recent changes: every returned result is current, and a later call may find more. Check index_state before concluding that new content is absent, and retry after a short, bounded delay instead of assuming the new content was searched.