Database Engine

Role

The database engine handles all direct device lookups, specification queries, filtered searches, and comparisons against the in-memory device database. It does NOT perform compatibility analysis (that is the chain engine's job) and does NOT search IFU/documentation (that is the vector engine's job).

When to use: spec lookups, device searches by dimension/manufacturer/category, device comparisons, extracting specific field values.

When NOT to use: compatibility checks ("Can I use X with Y?"), IFU/documentation lookups, clinical guidelines.

Architecture

User Query
    |
    v
QuerySpecAgent (LLM, fast model)
    |  Generates structured JSON query spec
    v
QueryExecutor (Pure Python)
    |  Executes query spec against DATABASE
    v
DatabaseOutputAgent (LLM, streaming)
    |  Formats results into natural language
    v
SSE Response

Filter path (used by query planner): Bypasses the LLM QuerySpecAgent entirely. The orchestrator's query planner provides a pre-built query spec with input_type: "filter", which goes directly to QueryExecutor.

Database Schema

Each device record in DATABASE is a flat dict keyed by numeric string ID (e.g., "56").

Identity Fields

Classification Fields

Dimension Fields

Compatibility Rule Fields (used by chain engine)

Category System

Devices are classified by category_type (precise) and conical_category (hierarchy level).

Category Type Values

User-Facing Category Mappings

When users mention a device category, the executor maps it to the correct category_type values:

Conical Category Hierarchy

L0 (outermost)  — Sheaths, guide catheters
  L1             — BGC, guide/intermediate catheters
    L2           — Aspiration, DAC, intermediate catheters
      L3         — Microcatheters, delivery catheters
        L4       — Stent systems
          L5     — Stent retrievers
        LW       — Guidewires

Higher L-number = goes INSIDE lower L-number.

QueryExecutor Actions Reference

get_device_specs

Purpose: Retrieve full specs for specific device IDs. Input: device_ids: string[] Output: Array of device spec objects with identity + specifications.

filter_by_spec

Purpose: Find devices matching a category and/or dimension filters. Input: category: string (optional), filters: [{field, operator, value}] (optional) Output: Array of matching device specs. Category matching: Uses category_type first (precise), falls back to conical_category for broad terms.

find_compatible

Purpose: Find devices that physically fit with a source device at a single connection point. Input: source_device_ids: string[], target_category: string, direction: "inner"|"outer", check_length: boolean Output: Array of compatible device specs with compatibility_reason. Note: This is a simplified OD/ID math check. For full compatibility analysis with all rules, use the chain engine.

compare_devices

Purpose: Pull specs for multiple devices side by side. Input: device_groups: string[][] — groups of device IDs to compare. Output: Array of all device specs (flattened from all groups).

extract_value

Purpose: Extract a specific field value from a previous step's results. Input: from_step: string, field: string, aggregation: "min"|"max"|"avg"|"first" Output: Single value (number or string).

search_both_id_od

Purpose: Search for devices by a dimension value when it's ambiguous whether the user means ID or OD. Input: category: string, dimension_value: float, dimension_operator: string, additional_filters: [{field, operator, value}] Output: {id_matches: [], od_matches: [], dimension_value, dimension_operator}

intersect

Purpose: Find devices common to multiple result sets. Input: from_steps: string[] Output: Array of devices present in ALL referenced steps.

union

Purpose: Combine multiple result sets (deduplicated by device_id). Input: from_steps: string[] Output: Array of unique devices from all referenced steps.

Field Name Mapping

The QuerySpecAgent uses friendly field names. The executor maps them to raw database fields:

Common Query Patterns