Ingest a single file. Auto-detects code/markdown/text.

Ingest raw text with optional type hint (code/markdown/text).

Ingest all supported files in a directory.

Supports all extensions in CodeChunker.LANGUAGE_MAP plus .md, .rst, .txt.

List all ingested documents with their metadata.

Delete an ingested document by its doc_id.

Hybrid search (vector + full-text + RRF) across all chunks.

Args: query: Natural language query. k: Number of results (max 50). source_type: Optional filter: "code", "markdown", or "text".

Returns: List of search results with text, source, score, and metadata.

Search with parent/sibling/child context expansion.

For each result, includes surrounding chunks (context_chunks before and after) so the LLM has full context.

Args: query: Natural language query. k: Number of primary results (max 20). context_chunks: Number of adjacent chunks to include (0-5). source_type: Optional filter: "code", "markdown", or "text".

Returns: List of results, each with a "context" field containing surrounding chunks.

Find chunks similar to a given chunk by ID.

Args: chunk_id: ID of the source chunk. k: Number of similar results to return (max 20).

Returns: List of similar chunks with scores and text snippets.

Search and return results formatted for LLM context building.

Args: query: Natural language query. k: Number of results (max 20). filters: Optional JSON string of filter conditions.

Returns: Formatted string with source citations.

Add an entity to the knowledge graph.

Args: name: Entity name (e.g., "MyClass", "Authentication", "Paris"). type: Entity type (class, function, concept, person, place, etc.). metadata: Optional metadata dict.

Returns: Created entity details including entity_id.

Add a directed relation between two entities.

Args: source_id: Source entity ID. target_id: Target entity ID. rel_type: Type of relation (CALLS, DEPENDS_ON, CONTAINS, etc.). weight: Relation strength (0.0 to 1.0).

Returns: Created relation details.

Search entities in the knowledge graph by name or type.

Args: query: Search term for entity name. type: Optional entity type filter. limit: Max results (max 100).

Returns: List of matching entities.

BFS traversal from a starting entity.

Args: start_entity_id: Entity ID to start from. max_depth: Max traversal depth (1-10).

Returns: List of (entity_id, name, type, depth) entries.

Get all relations for an entity (incoming and outgoing).

Args: entity_id: Entity ID.

Returns: List of relations with source/target info.

Run a SQL SELECT query over relational tables.

Full SQL supported: SELECT, JOIN, CTE, GROUP BY, window functions, subqueries, UNION, etc.

Available tables:

• documents: Document-level metadata (doc_id, source, source_type, chunk_count, file_size, file_hash, language, created_at)

• chunks: Individual text chunks (chunk_id, doc_id, chunk_index, source_type, chunk_type, entity_name, file_path, start_line, end_line, char_count)

• tags: Defined tags (tag_id, name, color, description)

• document_tags: Many-to-many mapping (doc_id, tag_id)

• metadata: Flexible key-value store (key, value, doc_id)

Examples: SELECT source_type, COUNT(*) as cnt FROM documents GROUP BY source_type SELECT * FROM chunks WHERE source_type = 'code' LIMIT 10 SELECT d.source, COUNT(c.chunk_id) as chunks FROM documents d JOIN chunks c ON d.doc_id = c.doc_id GROUP BY d.source ORDER BY chunks DESC SELECT d.source FROM documents d JOIN document_tags dt ON d.doc_id = dt.doc_id JOIN tags t ON dt.tag_id = t.tag_id WHERE t.name = 'important'

Args: query: SQL SELECT query string. limit: Max rows to return (default 100, max 5000).

Returns: Dict with "columns", "rows", and "row_count".

Execute a write SQL statement (INSERT, UPDATE, DELETE) with safety rails.

Safety rules enforced by the engine:

• DELETE/UPDATE without WHERE clause is BLOCKED

• DROP TABLE/DATABASE/SCHEMA is BLOCKED

Use parameterized ? placeholders for values to prevent injection. For SELECT queries, use sql_query instead.

Examples: INSERT INTO tags (name, color) VALUES ('urgent', 'red') UPDATE documents SET source_type = 'markdown' WHERE doc_id = 'abc-123' DELETE FROM document_tags WHERE doc_id = 'abc-123' INSERT INTO metadata (key, value, doc_id) VALUES ('reviewer', 'alice', 'abc-123')

Args: statement: SQL write statement (INSERT, UPDATE, DELETE).

Returns: Dict with "affected_rows" count, or "error" if blocked.

List all available relational tables with their schema.

Returns table name, column name, column type, and nullability for each column in every user table.

Create a new tag for categorizing documents.

Apply a tag to a document. Creates the tag if it doesn't exist.

Remove a tag from a document.

Get all tags applied to a document.

Set a metadata key-value pair, optionally scoped to a document.

Overwrites any existing value for the same key+doc_id combination.

Retrieve metadata entries, optionally filtered by key and/or doc_id.

Omit both to get all metadata. Filter by key to find all values for a key. Filter by doc_id to find all metadata for a document.

Sync data from LanceDB vector store into relational tables.

Call this after ingesting documents to make relational queries up to date. The sync is idempotent — call it anytime.

Get aggregate statistics about the document corpus via SQL.

Returns: total documents, total chunks, docs by type, chunks by type, average chunks per document, date range.

List all versions of the chunks table for time-travel.

Returns: List of version entries with version number, timestamp, and tag.

Tag a specific version for reference.

Args: version: Version number to tag. tag_name: Human-readable tag name (e.g., "v1.0", "before-refactor").

Returns: Confirmation with version and tag name.

Get database statistics.

Returns: Stats object with counts and storage info.

Check out a specific table version for time-travel queries.

Restore the table to a specific version.

Create a new branch from an optional version.

List all branches.

Switch to a specified branch.