Implement Agentic Multi-Step Chat Subsystem and Non-Blocking Architecture#176
Merged
Implement Agentic Multi-Step Chat Subsystem and Non-Blocking Architecture#176
Conversation
Implement a comprehensive context-aware search system for the AI assistant, supporting geographical targeting, universal page context analysis, and an agentic multi-step processing architecture. - Refactor ChatService into an agentic loop for multi-step intent fulfillment - Implement universal 'PageViewContext' to capture URL state on every page - Add backend resolver to translate raw paths/IDs into descriptive summaries - Implement logic to filter by cardinal directions (North, South, etc.) - Add 'Region Promotion' to automatically map towns to parent regions - Implement automatic country/region context resolution via coords or IP - Add JSON repair and retry logic to OpenAIService for increased reliability - Implement fuzzy location matching for specific dive site name resolution - Add 'intermediate_steps' and 'entity_type_filter' to chat schemas - Expand regression suite with complex geographical and contextual cases
Split the monolithic chat_service.py into a modular package to improve maintainability and readability. Extracted intent extraction, response generation, context resolution, weather enrichment, and search executors into dedicated modules within backend/app/services/chat/. Updated all routers and tests to use the new module structure while preserving exact functional parity.
Upgrade the chat subsystem from a rigid, single-step intent extraction pipeline to a multi-step ReAct (Reasoning and Acting) loop powered by OpenAI Tool Calling. This transition improves answer accuracy through self-correction and ambiguity handling while simplifying future feature extensibility. Adopt non-blocking architecture by migrating to AsyncOpenAI and delegating synchronous database operations to a thread pool. This resolves event loop lockups during intensive LLM or database tasks. Refine system prompts to eliminate domain hallucinations and enforce sensible safety defaults. Enhance the quality evaluation suite with tiered test cases and comprehensive logging to better monitor agent performance across all supported backend tools.
kargig
force-pushed
the
feature/cardinal-direction-filtering
branch
from
01d264c to
e3d0eda
Compare
kargig
changed the title
kargig
added a commit
that referenced
this pull request
Mar 10, 2026
…ture (#176) * Refactor chatbot to agentic architecture and add geographic targeting Implement a comprehensive context-aware search system for the AI assistant, supporting geographical targeting, universal page context analysis, and an agentic multi-step processing architecture. - Refactor ChatService into an agentic loop for multi-step intent fulfillment - Implement universal 'PageViewContext' to capture URL state on every page - Add backend resolver to translate raw paths/IDs into descriptive summaries - Implement logic to filter by cardinal directions (North, South, etc.) - Add 'Region Promotion' to automatically map towns to parent regions - Implement automatic country/region context resolution via coords or IP - Add JSON repair and retry logic to OpenAIService for increased reliability - Implement fuzzy location matching for specific dive site name resolution - Add 'intermediate_steps' and 'entity_type_filter' to chat schemas - Expand regression suite with complex geographical and contextual cases * Refactor chat service into modular architecture Split the monolithic chat_service.py into a modular package to improve maintainability and readability. Extracted intent extraction, response generation, context resolution, weather enrichment, and search executors into dedicated modules within backend/app/services/chat/. Updated all routers and tests to use the new module structure while preserving exact functional parity. * Implement agentic tool-calling loop for chatbot Upgrade the chat subsystem from a rigid, single-step intent extraction pipeline to a multi-step ReAct (Reasoning and Acting) loop powered by OpenAI Tool Calling. This transition improves answer accuracy through self-correction and ambiguity handling while simplifying future feature extensibility. Adopt non-blocking architecture by migrating to AsyncOpenAI and delegating synchronous database operations to a thread pool. This resolves event loop lockups during intensive LLM or database tasks. Refine system prompts to eliminate domain hallucinations and enforce sensible safety defaults. Enhance the quality evaluation suite with tiered test cases and comprehensive logging to better monitor agent performance across all supported backend tools.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR fundamentally transforms the Divemap chatbot from a rigid, single-step intent extraction pipeline into a robust, multi-step ReAct (Reasoning and Acting) agent powered by OpenAI Tool Calling. It also modernizes the backend architecture to be fully non-blocking, resolving event loop lockups during intensive AI or database tasks.
Changes Made
Core Chat Architecture
SearchIntentschema to discrete OpenAI Tool Calling. TheChatServicenow utilizes awhileloop allowing the LLM to execute multiple specialized tools in succession to fulfill complex queries.chat_service.pyinto a dedicatedbackend/app/services/chat/package with specialized modules for tool definitions, executors, and utilities.search_dive_sites: Spatial and keyword-based site discovery.search_diving_centers: Find dive centers with support for gear rental Fallbacks.search_marine_life: Biodiversity-focused discovery.calculate_diving_physics: High-precision physics engine (MOD, SAC, EAD, etc.).get_weather_suitability: Wind and safety forecast integration.recommend_dive_sites: Personalized, context-aware site suggestions.search_certifications: Knowledge base for diving agencies and career paths.ask_user_for_clarification: Allows the agent to pause and request missing data.Performance & Reliability
AsyncOpenAI.run_in_threadpool, ensuring the event loop remains free to serve other requests during chat processing..ai,.app).SearchIntentschemas to support polymorphic data types (strings/floats) in calculator parameters.Evaluation & Tooling
evaluate_chat_quality.pywith 6 tiers of test cases (Knowledge -> Basic Tools -> Complex Discovery -> Calculators -> Agentic Multi-Step).Testing
tests/test_chat_api.py,tests/test_api_chat_recommendation.py,tests/test_chat_comparison.py, etc.).6784a87to ensure no legacy filtering logic (snorkel heuristics, cardinal directions) was lost during refactoring./healthendpoints while multi-step agent loops were active.evaluate_chat_quality.pysuite achieving a high pass rate across all tool categories.Related Issues
Additional Notes
intentkey from the defaultChatResponseJSON as part of the move toward a tool-history-based architecture (preserved internal mappings for backward compatibility where possible).docker restart divemap_backendafter deployment to initialize the newAsyncOpenAIclient.backend/app/services/chat/chat_service.pywhich manages the multi-turn agent loop.