ducpy.search.search_elements¶

Element search helpers for .duc SQLite databases.

This module uses a hybrid strategy:

SQLite FTS5 narrows candidates quickly from the searchable DUC tables.
Python applies a second ranking pass that combines:
- FTS rank
- exact / prefix / substring behavior
- token coverage
- string similarity

The JSON output is shaped for downstream consumers that need:

the original query
total raw element hits
the ordered list of all matching element ids
result rows for individual elements or grouped file-backed elements

Attributes¶

DucSearchResult

Classes¶

`DucSearchResult`
`DucElementSearchResult`	One result row for a single element.
`DucFileSearchResult`	One grouped result row for repeated file-backed elements.
`DucSearchResponse`	Search response and JSON export metadata.

Functions¶

search_duc_elements(→ DucSearchResponse)

Search DUC elements and export ordered results to JSON.

Module Contents¶

class ducpy.search.search_elements.DucSearchResult¶: Compatibility placeholder for exported result types.

class ducpy.search.search_elements.DucElementSearchResult¶

One result row for a single element.

element_id: str¶

element_type: str¶

matches: list[str]¶

score: float¶

to_dict() → dict[str, Any]¶

class ducpy.search.search_elements.DucFileSearchResult¶

One grouped result row for repeated file-backed elements.

file_id: str¶

element_type: str¶

matches: list[str]¶

score: float¶

hits: int¶

element_ids: list[str]¶

to_dict() → dict[str, Any]¶

ducpy.search.search_elements.DucSearchResult¶

class ducpy.search.search_elements.DucSearchResponse¶

Search response and JSON export metadata.

query: str¶

results: list[DucSearchResult]¶

total_hits: int¶

all_element_ids: list[str]¶

output_path: str | None = None¶

to_dict() → dict[str, Any]¶: Convert the response to a JSON-friendly dictionary.

ducpy.search.search_elements.search_duc_elements(duc_path: str | pathlib.Path, query: str, *, output_path: str | pathlib.Path | None = None, limit: int = 50) → DucSearchResponse¶

Search DUC elements and export ordered results to JSON.

Args:

duc_path: Path to the .duc SQLite database. query: Plain-text search query. output_path: Optional JSON output path. When omitted, a file is created

next to the .duc file.

limit: Maximum number of ranked element results to keep.