Agentic DuckDB Source

This directory contains the core implementation of the Agentic DuckDB library, which provides an AI-friendly interface to DuckDB operations. The library is designed to make it easy to work with DuckDB databases in AI-powered applications.

Directory Structure

• DuckDbTools.ts - Core utility class for DuckDB operations
• duck-db.ts - AI-friendly wrapper with function decorators
• types/ - TypeScript type definitions
• index.ts - Main entry point and exports

Core Components

DuckDbTools

DuckDbTools is a utility class that provides low-level operations for interacting with DuckDB databases. Key features include:

• Database connection management
• SQL query execution
• Table creation and management
• Data import/export capabilities
• Full-text search functionality

Key methods:

• runQuery(query: string) - Execute SQL queries
• createTableFromPath(filePath: string, table?: string) - Create tables from files
• exportTableToPath(table: string, format: string) - Export tables to various formats
• createFtsIndex(table: string, uniqueKey: string, inputValues: string[]) - Create full-text search indices
• fullTextSearch(table: string, uniqueKey: string, searchText: string) - Perform full-text search

DuckDBClient

DuckDBClient provides an AI-friendly interface by wrapping DuckDbTools with AI function decorators. It extends AIFunctionsProvider and includes:

• AI-friendly method signatures with Zod schemas
• Simplified CSV loading from URLs
• Table inspection and schema management
• Query execution with AI-friendly interfaces

Key methods:

• loadCsvFromUrl(input: { fileUrl: string, tableName: string, options?: object }) - Load CSV data
• runQuery(input: { query: string }) - Execute SQL queries
• showTables(input: { verbose?: boolean }) - List database tables
• describeTable(input: { tableName: string }) - Get table schema information

Usage Example

import { DuckDBClient } from './index';

// Create a new DuckDB client
const client = new DuckDBClient();

// Load CSV data
await client.loadCsvFromUrl({
  fileUrl: 'https://example.com/data.csv',
  tableName: 'my_table',
  options: {
    delimiter: ',',
    header: true
  }
});

// Run a query
const results = await client.runQuery({
  query: 'SELECT * FROM my_table LIMIT 5'
});

Configuration

The library supports various configuration options through the DuckDbToolsConfig interface:

• dbPath - Path to the database file (defaults to in-memory)
• readOnly - Enable read-only mode
• initCommands - SQL commands to run on initialization
• config - Additional DuckDB configuration options

Dependencies

• duckdb - Core DuckDB database engine
• @agentic/core - AI function decorators and utilities
• zod - Runtime type checking and validation