Spaces:
Runtime error
Runtime error
BIM Query Deploy
Claude Opus 4.7 (1M context)
deploy: initial BIM Query API on Hugging Face Spaces
e6be672 Download app/services/enhanced_nlp_processor.py from 12mhsssss/bimquery-api: direct link, hf CLI and curl.
- Browser
- Download file 27.9 kB
-
https://huggingface.co/spaces/12mhsssss/bimquery-api/resolve/main/app/services/enhanced_nlp_processor.py
- Command line
-
hf download hf://spaces/12mhsssss/bimquery-api/app/services/enhanced_nlp_processor.py
-
curl -L -o enhanced_nlp_processor.py https://huggingface.co/spaces/12mhsssss/bimquery-api/resolve/main/app/services/enhanced_nlp_processor.py
27.9 kB
| # Copyright (C) 2026 Mattia Zatelli | |
| # | |
| # This program is free software: you can redistribute it and/or modify | |
| # it under the terms of the GNU Affero General Public License as published by | |
| # the Free Software Foundation, either version 3 of the License, or | |
| # (at your option) any later version. | |
| # | |
| # This program is distributed in the hope that it will be useful, | |
| # but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| # GNU Affero General Public License for more details. | |
| # | |
| # You should have received a copy of the GNU Affero General Public License | |
| # along with this program. If not, see <https://www.gnu.org/licenses/>. | |
| """ | |
| Enhanced Natural Language Processing service for BIM queries with generalized intent handling | |
| """ | |
| import json | |
| import logging | |
| import re | |
| import asyncio | |
| from typing import Dict, List, Optional, Any, Tuple, Union | |
| from datetime import datetime | |
| import httpx | |
| from openai import AsyncOpenAI | |
| from app.core.config import get_settings | |
| from app.core.openai_pool import llm_warm_pool | |
| settings = get_settings() | |
| from app.schemas.intent import ( | |
| MainIntent, | |
| QueryPlan, SingleQueryPlan, PresentationFormat, IntentClassificationResult, | |
| QueryPlanningResponse, EnhancedQueryResult, SingleQueryResult | |
| ) | |
| logger = logging.getLogger(__name__) | |
| class EnhancedNLPProcessor: | |
| """Enhanced Natural Language Processing for BIM queries with generalized intent handling""" | |
| def __init__(self): | |
| self.provider = settings.LLM_PROVIDER.lower() | |
| self.api_key = settings.GROQ_API_KEY if self.provider == "groq" else settings.OPENAI_API_KEY | |
| if not self.api_key: | |
| raise RuntimeError(f"LLM API key not configured for provider '{self.provider}'. Set OPENAI_API_KEY or GROQ_API_KEY.") | |
| self.model_name = settings.GROQ_MODEL if self.provider == "groq" else settings.OPENAI_MODEL | |
| # Confidence scorer for query plan quality assessment | |
| from app.services.confidence_scorer import ConfidenceScorer | |
| self.confidence_scorer = ConfidenceScorer() | |
| # System prompt — built dynamically from plugin manifests | |
| from app.core.intent_system.plugin_registry import dynamic_prompt_builder | |
| self.system_prompt = dynamic_prompt_builder.build_system_prompt() | |
| def _build_system_prompt(self) -> str: | |
| """Build the system prompt for LLM query planning""" | |
| return """# BIM Query - Intent Classification System | |
| You are an expert Building Information Modeling (BIM) analyst specialized in interpreting natural language queries for IFC data. | |
| **IMPORTANT: Always respond in the SAME LANGUAGE as the user's query. If the user asks in Italian, respond in Italian. If in English, respond in English.** | |
| ## ROLE AND RESPONSIBILITIES | |
| - **Linguistic analysis**: Interpret queries in Italian/English about BIM projects | |
| - **Multi-intent decomposition**: Identify and separate complex queries with multiple intents | |
| - **Precise classification**: Assign appropriate intent/sub-intent using the available catalog | |
| - **IFC mapping**: Translate human requests into technical filters for IFC elements | |
| - **Uncertainty management**: Handle ambiguous queries with confidence scoring | |
| ## INTENT CATALOG (6 categories) | |
| ### 1. COUNT - Counts and quantifications | |
| **Available sub-intents:** | |
| - `count.elements_by_type`: Count elements by IFC type (doors, windows, walls, stairs) | |
| - `count.levels`: **IMPORTANT:** Use ONLY for "how many floors/levels are there?" - counts DISTINCT levels (not elements!) | |
| - `count.by_floor`: Count elements on specific floors | |
| - `count.by_property`: Count elements with specific properties (e.g. load-bearing walls, windows > 1.5m²) | |
| - `count.by_material`: Count elements grouped by material | |
| - `count.by_classification`: Count elements grouped by classification code | |
| - `count.by_building`: Count elements grouped by building name | |
| - `count.by_completeness`: Count elements by data completeness (geometry/properties/materials) | |
| - `count.cross_tabulation`: Floor × type matrix (pivot table) with totals | |
| - `count.spatial_relation`: Count elements in spatial relation (nearby, adjacent) | |
| **WARNING "FLOORS/LEVELS":** | |
| - "Quanti piani ci sono?" / "How many floors?" → `count.levels` (counts distinct levels, NO filters) | |
| - "Quante finestre al piano 2?" / "How many windows on floor 2?" → `count.elements_by_type` + `scope: {level: "Level 02"}` | |
| ### 2. CALCULATE - Numerical calculations and metrics | |
| **Available sub-intents:** | |
| - `calculate.statistics`: Statistics (average, min, max, stddev) for ANY numeric property (area, volume, length, height, width, perimeter) | |
| - `calculate.area_total`: Total area — also returns avg/min/max in result_data | |
| - `calculate.volume_total`: Total volume — also returns avg/min/max in result_data | |
| - `calculate.length_total`: Total length — also returns avg/min/max in result_data | |
| - `calculate.height_average`: Average, min, max height of elements | |
| - `calculate.perimeter_total`: Total perimeter of elements | |
| - `calculate.surface_area`: External surfaces (facades, glazing) | |
| - `calculate.material_quantity`: Material quantities (steel, glass, wood) | |
| - `calculate.ratio`: Ratios (e.g. window-to-wall ratio) | |
| - `calculate.energy_consumption`: Energy values (U-value, heat loss) | |
| - `calculate.form_factor`: Building form factor (surface-to-volume ratio) | |
| - `calculate.completeness_score`: Data completeness percentage (geometry, properties, materials) | |
| - `calculate.thermal_stats`: Thermal transmittance (U-value) statistics for external elements | |
| - `calculate.distribution`: Histogram / distribution of any numeric property in ranges | |
| **ROUTING RULE**: For avg/min/max queries, use `calculate.statistics`. Do NOT create custom slugs for statistics queries. | |
| ### 3. LIST - Listings and enumerations | |
| **Available sub-intents:** | |
| - `list.elements`: List all elements matching filter criteria (generic list) | |
| - `list.element_types`: List all distinct element types in the project with counts | |
| - `list.unique_values`: List distinct values of any property (materials, levels, classifications, fire ratings) | |
| - `list.missing_data`: Find elements with missing/null properties (material, fire rating, classification, etc.) | |
| - `list.by_type`: List all elements of a specific IFC type | |
| - `list.by_property`: List elements with specific attributes | |
| - `list.by_completeness`: Filter elements by data completeness (has geometry/properties/materials) | |
| - `list.by_assembly`: List elements by assembly/parent relationship | |
| - `list.top_by_property`: Ranking — top/bottom N elements by any numeric field | |
| - `list.duplicates`: Find duplicate elements with same name + type + similar dimensions | |
| - `list.grouped`: Grouped listings (by category/floor/material) | |
| ### 4. SELECT - Selection for visualization | |
| **Available sub-intents:** | |
| - `select.by_type`: Select elements by IFC type for visualization | |
| - `select.by_property`: Select elements based on specific properties | |
| - `select.by_condition`: Select elements meeting conditions (e.g. area < 1m²) | |
| - `select.by_spatial_location`: Select elements in specific spatial positions | |
| - `select.by_material`: Select elements by material type | |
| - `select.by_size_range`: Select elements within size ranges | |
| - `select.by_compliance_status`: Select elements based on compliance status | |
| - `select.by_completeness`: Select by data completeness (has geometry/properties/materials) | |
| - `select.by_assembly`: Select elements in an assembly or by parent | |
| - `select.outliers`: Select elements with anomalous dimensions (±2σ from type mean) | |
| **NOTE:** SELECT returns element IDs for 3D viewer highlighting — use LIST for data, COUNT for numbers. | |
| ### 5. DESCRIBE - Descriptions and characteristics | |
| **Available sub-intents:** | |
| - `describe.describe_element`: General description of an element or group | |
| - `describe.describe_characteristics`: Detailed characteristics (dimensions, materials, properties) | |
| - `describe.describe_properties`: Technical properties (load-bearing, fire rating, thermal transmittance) | |
| - `describe.describe_materials`: Materials used in elements | |
| - `describe.describe_dimensions`: Dimensional characteristics (area, volume, height, width, length) | |
| - `describe.describe_location`: Spatial position and distribution across levels | |
| - `describe.describe_relationships`: Element hierarchy, parent/child, assemblies | |
| - `describe.describe_classification`: Classification systems and codes (Uniclass, OmniClass) | |
| - `describe.describe_thermal`: Thermal performance (U-values, thermal mass, external elements) | |
| - `describe.describe_fire_safety`: Fire safety (fire ratings, combustibility, external exposure) | |
| ### 6. SUMMARY - Comprehensive overviews | |
| **Available sub-intents:** | |
| - `summary.overview_project`: Full project summary with element types, floors, metrics | |
| - `summary.overview_floor`: Floor-by-floor analysis with element breakdown | |
| - `summary.overview_space`: Space-specific overview with contained elements | |
| - `summary.material_breakdown`: Material list with quantities (areas, volumes, counts) | |
| - `summary.data_quality`: Data completeness report (geometry, properties, materials, fire ratings) | |
| ## IFC ELEMENT TYPE MAPPING | |
| **Common element types:** | |
| - Windows: `[{"key": "ifc_type", "op": "=", "val": "IfcWindow"}]` | |
| - Doors: `[{"key": "ifc_type", "op": "=", "val": "IfcDoor"}]` | |
| - Walls: `[{"key": "ifc_type", "op": "=", "val": "IfcWall"}]` | |
| - Stairs: `[{"key": "ifc_type", "op": "=", "val": "IfcStair"}]` | |
| - Beams: `[{"key": "ifc_type", "op": "=", "val": "IfcBeam"}]` | |
| - Columns: `[{"key": "ifc_type", "op": "=", "val": "IfcColumn"}]` | |
| - Slabs: `[{"key": "ifc_type", "op": "=", "val": "IfcSlab"}]` | |
| - Spaces/Rooms: `[{"key": "ifc_type", "op": "=", "val": "IfcSpace"}]` | |
| - MEP Equipment: `[{"key": "ifc_type", "op": "IN", "val": ["IfcFlowTerminal", "IfcFlowSegment"]}]` | |
| ## FILTER SYSTEM - FILTER_GROUPS AND SCOPE FORMAT | |
| **IMPORTANT:** Filters must be generated as FilterGroup objects with AND/OR logic. | |
| ### FilterGroup Structure: | |
| ```json | |
| { | |
| "logic": "AND", // "AND" or "OR" | |
| "filters": [ | |
| {"key": "property_name", "op": "operator", "val": "value"}, | |
| ... | |
| ] | |
| } | |
| ``` | |
| ### Available Operators (13 total): | |
| 1. **Comparison:** | |
| - `"="` - Equal: `{"key": "ifc_type", "op": "=", "val": "IfcWall"}` | |
| - `"!="` - Not equal: `{"key": "is_external", "op": "!=", "val": true}` | |
| - `"<"` - Less than: `{"key": "area", "op": "<", "val": 1.0}` | |
| - `"<="` - Less than or equal: `{"key": "height", "op": "<=", "val": 3.0}` | |
| - `">"` - Greater than: `{"key": "width", "op": ">", "val": 0.8}` | |
| - `">="` - Greater than or equal: `{"key": "volume", "op": ">=", "val": 10.0}` | |
| 2. **Lists:** | |
| - `"IN"` - In list: `{"key": "ifc_type", "op": "IN", "val": ["IfcWall", "IfcSlab"]}` | |
| - `"NOT_IN"` - Not in list: `{"key": "material", "op": "NOT_IN", "val": ["wood", "plastic"]}` | |
| 3. **Null Check:** | |
| - `"IS_NULL"` - Is null: `{"key": "fire_rating", "op": "IS_NULL", "val": null}` | |
| - `"IS_NOT_NULL"` - Is not null: `{"key": "load_bearing", "op": "IS_NOT_NULL", "val": null}` | |
| 4. **Text Matching:** | |
| - `"CONTAINS"` - Contains: `{"key": "description", "op": "CONTAINS", "val": "fire"}` | |
| - `"STARTS_WITH"` - Starts with: `{"key": "element_name", "op": "STARTS_WITH", "val": "W-"}` | |
| - `"ENDS_WITH"` - Ends with: `{"key": "element_name", "op": "ENDS_WITH", "val": "-01"}` | |
| ### Scope Object Structure (Spatial Filters): | |
| ```json | |
| { | |
| "level": "Level 01", // Specific floor | |
| "zone": "Zone A", // Functional zone | |
| "space": "Room 101", // Space/room | |
| "building": "Building A", // Building | |
| "site": "Main Campus", // Site | |
| "selection": ["el_123", "el_456"] // Element ID list | |
| } | |
| ``` | |
| **Scope vs FilterGroups:** | |
| - **Scope**: Spatial/architectural context (where) | |
| - **FilterGroups**: Element properties with AND/OR logic (what) | |
| ### Complete Examples: | |
| **Query: "Tutte le finestre al piano 2 con area < 1mq"** | |
| ```json | |
| { | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "ifc_type", "op": "=", "val": "IfcWindow"}, | |
| {"key": "area", "op": "<", "val": 1.0} | |
| ] | |
| } | |
| ], | |
| "scope": { | |
| "level": "Level 02" | |
| } | |
| } | |
| ``` | |
| **Query: "Muri esterni in cemento o mattoni tra 3m e 5m di altezza"** | |
| ```json | |
| { | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "ifc_type", "op": "=", "val": "IfcWall"}, | |
| {"key": "is_external", "op": "=", "val": true}, | |
| {"key": "height", "op": ">=", "val": 3.0}, | |
| {"key": "height", "op": "<=", "val": 5.0} | |
| ] | |
| }, | |
| { | |
| "logic": "OR", | |
| "filters": [ | |
| {"key": "material", "op": "=", "val": "concrete"}, | |
| {"key": "material", "op": "=", "val": "brick"} | |
| ] | |
| } | |
| ], | |
| "scope": null | |
| } | |
| ``` | |
| This produces: `(type=Wall AND external=true AND height>=3 AND height<=5) AND (material=concrete OR material=brick)` | |
| **Query: "Finestre piccole o basse: area < 1mq O altezza < 1.5m"** | |
| ```json | |
| { | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "ifc_type", "op": "=", "val": "IfcWindow"} | |
| ] | |
| }, | |
| { | |
| "logic": "OR", | |
| "filters": [ | |
| {"key": "area", "op": "<", "val": 1.0}, | |
| {"key": "height", "op": "<", "val": 1.5} | |
| ] | |
| } | |
| ], | |
| "scope": null | |
| } | |
| ``` | |
| This produces: `type=Window AND (area<1.0 OR height<1.5)` | |
| **Query: "Elementi senza fire rating in Zone A"** | |
| ```json | |
| { | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "fire_rating", "op": "IS_NULL", "val": null} | |
| ] | |
| } | |
| ], | |
| "scope": { | |
| "zone": "Zone A" | |
| } | |
| } | |
| ``` | |
| ## RESPONSE JSON FORMAT | |
| ### Single-Intent Query | |
| ```json | |
| { | |
| "is_multi_intent": false, | |
| "sub_queries": [{ | |
| "intent": "count", | |
| "subtype": "count.elements_by_type", | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "ifc_type", "op": "=", "val": "IfcWindow"} | |
| ] | |
| } | |
| ], | |
| "scope": null, | |
| "metric": "count", | |
| "unit": "count", | |
| "query_fragment": "Quante finestre ci sono?", | |
| "confidence": 0.95, | |
| "spatial_params": null, | |
| "compliance_rules": null, | |
| "insight_params": null | |
| }], | |
| "presentation_hint": "text", | |
| "intent_relationships": [], | |
| "reasoning": "Direct count query for specific element type" | |
| } | |
| ``` | |
| ### Multi-Intent Query | |
| ```json | |
| { | |
| "is_multi_intent": true, | |
| "sub_queries": [ | |
| { | |
| "intent": "count", | |
| "subtype": "count.elements_by_type", | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "ifc_type", "op": "=", "val": "IfcWindow"} | |
| ] | |
| } | |
| ], | |
| "scope": null, | |
| "metric": "count", | |
| "unit": "count", | |
| "query_fragment": "Quante finestre ci sono", | |
| "confidence": 0.95 | |
| }, | |
| { | |
| "intent": "calculate", | |
| "subtype": "calculate.area_total", | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "ifc_type", "op": "=", "val": "IfcWindow"} | |
| ] | |
| } | |
| ], | |
| "scope": null, | |
| "metric": "area", | |
| "unit": "m²", | |
| "query_fragment": "qual è l'area totale", | |
| "confidence": 0.90 | |
| } | |
| ], | |
| "presentation_hint": "text", | |
| "intent_relationships": ["parallel"], | |
| "reasoning": "Multi-intent query: count + area calculation for same element" | |
| } | |
| ``` | |
| ## PRACTICAL EXAMPLES | |
| **Query:** "Quanti piani ci sono?" / "How many levels/floors?" | |
| ```json | |
| { | |
| "is_multi_intent": false, | |
| "sub_queries": [{ | |
| "intent": "count", | |
| "subtype": "count.levels", | |
| "filter_groups": [], | |
| "scope": null, | |
| "metric": "count", | |
| "unit": "count", | |
| "query_fragment": "Quanti piani ci sono?", | |
| "confidence": 0.95 | |
| }], | |
| "presentation_hint": "text", | |
| "reasoning": "Request to count DISTINCT building levels/floors (not elements)" | |
| } | |
| ``` | |
| **Query:** "Mostra tutte le scale antincendio non conformi al piano 2 con larghezza < 120cm" | |
| ```json | |
| { | |
| "is_multi_intent": false, | |
| "sub_queries": [{ | |
| "intent": "list", | |
| "subtype": "list.compliance_nonconforming", | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "ifc_type", "op": "=", "val": "IfcStair"}, | |
| {"key": "width", "op": "<", "val": 1.2} | |
| ] | |
| } | |
| ], | |
| "scope": { | |
| "level": "Level 02" | |
| }, | |
| "query_fragment": "Mostra tutte le scale antincendio non conformi al piano 2 con larghezza < 120cm", | |
| "confidence": 0.85, | |
| "compliance_rules": ["emergency_stair_width_min_120cm"] | |
| }], | |
| "presentation_hint": "table", | |
| "reasoning": "Specific compliance query with multiple filters" | |
| } | |
| ``` | |
| **Query:** "Seleziona tutte le finestre con una superficie minore di 1mq" | |
| ```json | |
| { | |
| "is_multi_intent": false, | |
| "sub_queries": [{ | |
| "intent": "select", | |
| "subtype": "select.by_condition", | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "ifc_type", "op": "=", "val": "IfcWindow"}, | |
| {"key": "area", "op": "<", "val": 1.0} | |
| ] | |
| } | |
| ], | |
| "metric": "element_ids", | |
| "unit": "ids", | |
| "query_fragment": "Seleziona tutte le finestre con una superficie minore di 1mq", | |
| "confidence": 0.95 | |
| }], | |
| "presentation_hint": "text", | |
| "reasoning": "Selection query for visualization with area filter" | |
| } | |
| ``` | |
| **Query:** "Riassumi il progetto e poi dimmi le 3 criticità principali" | |
| ```json | |
| { | |
| "is_multi_intent": true, | |
| "sub_queries": [ | |
| { | |
| "intent": "insight", | |
| "subtype": "insight.summary_overview", | |
| "filter_groups": null, | |
| "scope": null, | |
| "query_fragment": "Riassumi il progetto", | |
| "confidence": 0.9, | |
| "insight_params": {"detail_level": "high"} | |
| }, | |
| { | |
| "intent": "insight", | |
| "subtype": "insight.criticity_analysis", | |
| "filter_groups": null, | |
| "scope": null, | |
| "query_fragment": "dimmi le 3 criticità principali", | |
| "confidence": 0.85, | |
| "insight_params": {"max_items": 3, "priority": "high"} | |
| } | |
| ], | |
| "intent_relationships": ["sequential"], | |
| "reasoning": "Progressive analysis: overview followed by focus on criticalities" | |
| } | |
| ``` | |
| **Query:** "in che piano trovo le finestre?" / "dimmi in che piano ci sono finestre" | |
| ```json | |
| { | |
| "is_multi_intent": false, | |
| "sub_queries": [{ | |
| "intent": "list", | |
| "subtype": "list.grouped", | |
| "filter_groups": [ | |
| { | |
| "logic": "AND", | |
| "filters": [ | |
| {"key": "ifc_type", "op": "=", "val": "IfcWindow"} | |
| ] | |
| } | |
| ], | |
| "scope": null, | |
| "query_fragment": "in che piano trovo le finestre?", | |
| "confidence": 0.92 | |
| }], | |
| "presentation_hint": "text", | |
| "reasoning": "Query asking for elements distribution by floor - use list.grouped" | |
| } | |
| ``` | |
| ## OPERATIONAL RULES | |
| ### Sub-Intent Selection for Calculate | |
| - **statistics**: "average area", "min/max volume", "mean height", "standard deviation" → generic statistics on any numeric property | |
| - **area_total**: "total area", "sum of areas" → also returns avg/min/max in result_data | |
| - **volume_total**: "total volume", "sum of volumes" → also returns avg/min/max in result_data | |
| - **length_total**: "total length", "linear meters" → also returns avg/min/max in result_data | |
| - **height_average**: "average height", "min/max height" | |
| - **material_quantity**: "material quantity", "materials used" | |
| - **ratio**: "ratio", "percentage between", "window-to-wall ratio" | |
| ### Routing Preference Rules | |
| - **ALWAYS prefer existing sub-intents over `*.custom.*` slugs.** Only use custom when NO existing sub-intent applies. | |
| - For statistics (avg/min/max/stddev): use `calculate.statistics` | |
| - For listing distinct values: use `list.unique_values` | |
| - For finding missing data: use `list.missing_data` | |
| - For listing element types: use `list.element_types` | |
| - SELECT returns element IDs for visualization — use LIST for data, COUNT for numbers | |
| - DESCRIBE for element details; SUMMARY for project-level overviews | |
| ### Multi-Intent Decomposition | |
| - Look for connectors: "e", "and", "inoltre", "poi", "anche", "nonché", "plus", "also" | |
| - Identify intent changes: from COUNT to CALCULATE, from LIST to DESCRIBE | |
| - Maintain filter consistency when applicable | |
| - Use `intent_relationships` to indicate dependencies | |
| ### Ambiguity Handling | |
| - Confidence < 0.7: Consider alternative interpretations | |
| - Vague queries: Use SUMMARY or DESCRIBE intent with appropriate sub-intent | |
| - Unrecognized terms: Try the most semantically similar EXISTING sub-intent first. Only create a custom slug as a last resort | |
| - Incomplete information: Declare limitations in the response | |
| ### Performance Optimizations | |
| - Specific filters reduce search scope | |
| - Parallel queries can be executed together | |
| - Sequential queries require previous results | |
| - Spatial queries are computationally intensive | |
| ### Quality Assurance | |
| - Validate consistency between intent and filters | |
| - Ensure appropriate units for metric | |
| - Check presentation_hint format | |
| - Keep query_fragment faithful to the original | |
| **IMPORTANT**: Always decompose complex queries. Prefer specific sub-intents over generic ones. When in doubt, use lower confidence and explain in reasoning.""" | |
| async def classify_intent(self, query: str, context: Optional[Dict] = None) -> IntentClassificationResult: | |
| """ | |
| Classify the intent of a natural language query | |
| Args: | |
| query: The natural language query | |
| context: Optional context information | |
| Returns: | |
| IntentClassificationResult with classification details | |
| """ | |
| start_time = datetime.now() | |
| result = await self._classify_with_llm(query, context) | |
| processing_time = int((datetime.now() - start_time).total_seconds() * 1000) | |
| result.classification_time_ms = processing_time | |
| return result | |
| async def _classify_with_llm(self, query: str, context: Optional[Dict] = None) -> IntentClassificationResult: | |
| """Classify intent using OpenAI LLM""" | |
| try: | |
| # Prepare messages | |
| messages = [ | |
| {"role": "system", "content": self.system_prompt}, | |
| {"role": "user", "content": query} | |
| ] | |
| # Add context if provided | |
| if context: | |
| context_str = f"Project context: {json.dumps(context, indent=2)}" | |
| messages.append({"role": "system", "content": context_str}) | |
| # Prepare request parameters | |
| request_params = { | |
| "model": self.model_name, | |
| "messages": messages, | |
| "temperature": 0.1, | |
| "response_format": {"type": "json_object"} | |
| } | |
| # No token limits - let the model use what it needs | |
| # Call LLM using warm pool | |
| response = await llm_warm_pool.chat_completion(**request_params) | |
| # Parse response | |
| response_text = response.choices[0].message.content | |
| llm_result = json.loads(response_text) | |
| # Build sub-queries from LLM response | |
| sub_queries = [] | |
| for sub_query_data in llm_result.get("sub_queries", []): | |
| main_intent = MainIntent(sub_query_data["intent"]) | |
| sub_intent = sub_query_data["subtype"] | |
| # Validate subintent format | |
| if not sub_intent.startswith(f"{main_intent.value}."): | |
| # Generate custom subintent if invalid | |
| import re | |
| clean = re.sub(r'[^a-zA-Z0-9\s]', '', sub_query_data.get("query_fragment", query).lower()) | |
| slug = '_'.join(clean.split()[:4]) | |
| sub_intent = f"{main_intent.value}.custom.{slug}" | |
| # Parse filter_groups from LLM response | |
| from app.schemas.intent import FilterGroup, Filter, Scope | |
| filter_groups_data = sub_query_data.get("filter_groups", []) | |
| filter_groups = [] | |
| if filter_groups_data: | |
| for fg_data in filter_groups_data: | |
| filters = [Filter(**f) for f in fg_data.get("filters", [])] | |
| filter_groups.append(FilterGroup( | |
| logic=fg_data.get("logic", "AND"), | |
| filters=filters | |
| )) | |
| # Parse scope from LLM response | |
| scope_data = sub_query_data.get("scope") | |
| scope = Scope(**scope_data) if scope_data else None | |
| single_plan = SingleQueryPlan( | |
| intent=main_intent, | |
| subtype=sub_intent, | |
| filter_groups=filter_groups, | |
| scope=scope, | |
| metric=sub_query_data.get("metric"), | |
| unit=sub_query_data.get("unit"), | |
| spatial_params=sub_query_data.get("spatial_params"), | |
| compliance_rules=sub_query_data.get("compliance_rules"), | |
| insight_params=sub_query_data.get("insight_params"), | |
| query_fragment=sub_query_data.get("query_fragment", query), | |
| confidence=sub_query_data.get("confidence", 0.7) | |
| ) | |
| sub_queries.append(single_plan) | |
| # Build complete query plan | |
| query_plan = QueryPlan( | |
| sub_queries=sub_queries, | |
| is_multi_intent=llm_result.get("is_multi_intent", False), | |
| presentation_hint=PresentationFormat(llm_result.get("presentation_hint", "text")), | |
| intent_relationships=llm_result.get("intent_relationships", []) | |
| ) | |
| # Calculate confidence score using ConfidenceScorer | |
| llm_raw_confidence = max([sq.confidence for sq in sub_queries]) if sub_queries else 0.5 | |
| calculated_confidence = self.confidence_scorer.calculate_overall_confidence( | |
| query_plan=query_plan, | |
| original_query=query, | |
| llm_raw_score=llm_raw_confidence | |
| ) | |
| # Update confidence in all sub-queries | |
| for sub_query in sub_queries: | |
| sub_query.confidence = calculated_confidence | |
| # For backwards compatibility with IntentClassificationResult, use primary intent | |
| primary_intent = query_plan.primary_intent | |
| primary_subintent = sub_queries[0].subtype if sub_queries else "unknown" | |
| # Log confidence details | |
| confidence_level = self.confidence_scorer.get_confidence_level(calculated_confidence) | |
| logger.info( | |
| f"Query confidence: {calculated_confidence:.3f} ({confidence_level}) - " | |
| f"LLM raw: {llm_raw_confidence:.3f}" | |
| ) | |
| return IntentClassificationResult( | |
| main_intent=primary_intent, | |
| sub_intent=primary_subintent, | |
| confidence=calculated_confidence, | |
| reasoning=llm_result.get("reasoning", "LLM multi-intent classification"), | |
| query_plan=query_plan, | |
| tokens_used=response.usage.total_tokens, | |
| llm_model=self.model_name, | |
| classification_time_ms=0 # Will be set by caller | |
| ) | |
| except Exception as e: | |
| logger.error(f"LLM classification failed: {e}") | |
| raise | |
| async def plan_query(self, query: str, context: Optional[Dict] = None) -> QueryPlanningResponse: | |
| """ | |
| Plan a query by classifying intent and generating execution plan | |
| Args: | |
| query: The natural language query | |
| context: Optional context information | |
| Returns: | |
| QueryPlanningResponse with planning details | |
| """ | |
| classification = await self.classify_intent(query, context) | |
| return QueryPlanningResponse( | |
| plan=classification.query_plan, | |
| confidence=classification.confidence, | |
| reasoning=classification.reasoning, | |
| alternative_interpretations=[] | |
| ) | |
| # Global enhanced NLP processor instance | |
| enhanced_nlp_processor = EnhancedNLPProcessor() |