siftdb 0.2.2

Python client library for SiftDB HTTP API

SiftDB Python Client

The official Python client library for SiftDB HTTP API.

Installation

pip install siftdb

Quick Start

Basic Usage

from siftdb import SiftDBClient

# Create client instance
client = SiftDBClient(
    base_url="http://localhost:8080",
    default_collection="/path/to/my/collection"
)

# Search for text
results = client.search(
    query="function main",
    path_filter="**/*.py",
    limit=50
)

print(f"Found {results.total_matches} matches in {results.duration_ms}ms")
for hit in results.results:
    print(f"{hit.file_path}:{hit.line_number}: {hit.line_content}")

Context Manager Usage

with SiftDBClient(base_url="http://localhost:8080") as client:
    results = client.search("error handling")
    print(f"Found {len(results.results)} results")

Import Files

# Import files into a collection
import_result = client.import_files(
    source_path="/path/to/source",
    include_patterns=["**/*.py", "**/*.md"],
    exclude_patterns=["**/__pycache__/**", "**/.*"]
)

print(f"Imported {import_result.files_ingested} files")
print(f"Skipped {import_result.files_skipped} files")
if import_result.errors > 0:
    print(f"Encountered {import_result.errors} errors")

List Collections

# List available collections
collections = client.list_collections()
for collection in collections.collections:
    print(f"{collection.name}: {collection.total_files} files, {collection.total_size_bytes} bytes")

Health Check

# Check server health
health = client.health()
print(f"Server status: {health.status}")
print(f"Server version: {health.version}")

API Reference

Client Configuration

SiftDBClient(
    base_url="http://localhost:8080",  # Server URL
    timeout=30,                        # Request timeout in seconds
    default_collection="/path/to/db"   # Default collection path
)

Search Parameters

client.search(
    query="search text",           # Required: search query
    collection="/path/to/db",      # Optional: override default collection
    path_filter="**/*.py",         # Optional: glob pattern for file filtering
    regex=False,                   # Optional: treat query as regex
    limit=1000                     # Optional: max results
)

Import Parameters

client.import_files(
    source_path="/path/to/source",         # Required: source directory
    collection="/path/to/collection",      # Optional: override default collection
    include_patterns=["**/*.py"],          # Optional: files to include
    exclude_patterns=["**/build/**"]       # Optional: files to exclude
)

Error Handling

from siftdb import SiftDBClient, SiftDBException

try:
    client = SiftDBClient()
    results = client.search("my query")
except SiftDBException as e:
    print(f"SiftDB Error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Data Models

SearchResponse

@dataclass
class SearchResponse:
    query: str                    # Original search query
    total_matches: int           # Total number of matches
    results: List[SearchResult]  # Search results
    duration_ms: float          # Search duration

SearchResult

@dataclass
class SearchResult:
    file_path: str      # File path of the match
    line_number: int    # Line number where match occurred
    line_content: str   # Content of the matching line

ImportResponse

@dataclass
class ImportResponse:
    message: str          # Import completion message
    files_ingested: int   # Number of files imported
    files_skipped: int    # Number of files skipped
    errors: int          # Number of errors encountered
    duration_ms: float   # Import duration

Requirements

• Python 3.8+
• requests >= 2.25.0

License

MIT