How yazeedmshayekh2/corereports works
1. Repository shape
- This is an AI assistant for insurance data analysis, split into a web/chat UI, a core orchestration layer, an agent layer, an AI model layer, and an Oracle database layer.
- It also includes a CLI/interactive mode, so the same intelligence system can be used both from a browser and from the command line.
2. User-facing presentation layer
- frontend/templates/chatbot.html plus frontend/static/js/chatbot.js and frontend/static/css/chatbot.css form the chat interface.
- The browser UI is responsible for capturing user prompts, rendering responses, and likely handling streaming/progressive output from the backend.
3. Application entrypoints
- src/K2/app.py is the main application entrypoint for the runnable system.
- src/K2/aims_view/core/main.py provides the non-web entrypoint for interactive/demo CLI usage.
- This suggests two execution paths that converge on the same orchestration and agent stack.
4. Central orchestration boundary
- src/K2/aims_view/agents/intelligence_manager.py is the main coordination layer.
- It acts as the brain of the system, deciding which agents to invoke, in what order, and when to retry or refine a query.
- The readme describes multi-cycle problem solving, strategic planning, execution, and streaming response generation as key behaviors here.
5. Intelligence agent pipeline
- The core agent set under agents/intelligence/ represents a staged reasoning workflow:
- strategic_planner.py decides the approach.
- schema_analyst.py inspects database structure.
- query_architect.py designs SQL.
- execution_specialist.py runs the query.
- computational_analyst.py performs calculations/analytics.
- results_evaluator.py checks output quality.
- response_generator.py turns results into a final answer.
- Architecturally, this is a pipeline from natural language to structured database action to final response.
6. Specialized entity-resolution layer
- agents/specialized/ contains support agents for customer/name handling:
- name_detector.py
- customer_validator.py
- name_matcher.py
- These likely resolve user mentions to real insurance customer records before query execution, which is important for accuracy in domain-specific conversations.
7. AI/LLM infrastructure
- src/K2/aims_view/ai/llm_factory.py centralizes creation of model clients.
- The readme indicates the system uses Gemini 2.5 Flash and Groq LLaMA 3.3 70B, with streaming support.
- security/ssl_config.py provides enterprise SSL-bypass configuration, which is an infrastructure concern rather than business logic.
8. Domain knowledge and prompt/context assembly
- core/domain_knowledge.py is a key boundary: it contains AIMS-specific insurance knowledge, field patterns, business rules, organizational structure, and calculation logic.
- utils/context_builder.py and utils/query_utils.py turn that knowledge into usable prompt/context material and clean/validate SQL.
- This means the system is not just LLM-driven; it is grounded by explicit domain rules.
9. Database access layer
- src/K2/aims_view/database/database.py is the Oracle integration layer.
- The readme and docs indicate environment-based Oracle credentials and service settings, so the assistant depends on an external Oracle database for actual business data.
- The architecture implies a strict boundary: agents generate or refine SQL, while the database module owns connection/execution details.
10. Conversation state and memory
- memory/conversation_memory.json stores conversation history or session memory.
- utils/memory_utils.py likely manages reading/writing or formatting that memory for context reuse.
- This persistence layer supports follow-up questions and multi-turn reasoning.
11. Security and operational concerns
- The readme calls out input validation, sanitization, SQL injection prevention, rate limiting, and logging.
- In architectural terms, these are cross-cutting controls wrapping the query-generation and database-execution path, not separate business features.
12. Configuration and runtime dependencies
- config.json holds system configuration for models, cycles/thresholds, agent behavior, and database settings.
- External runtime dependencies are important here: the app needs API keys for Gemini and Groq, plus Oracle connection variables.
- So the system is effectively a coordinated service that bridges UI input → AI reasoning → Oracle data retrieval → natural-language response.
Main entry points: intelligence_manager.py Intelligence Manager · strategic_planner.py Planner · execution_specialist.py Execution Specialist · chatbot.js Chat JS
Components 25
UI
Browser-facing chat interface and client-side behavior.
Entrypoints
Web and CLI startup paths that converge on the same core system.
- Web App · Main runnable application entry for the browser-based system.
src/K2/app.py - CLI Main · Non-web interactive/demo entry path.
src/K2/aims_view/core/main.py - Interactive · Console interaction loop and demo-style usage flow.
src/K2/aims_view/core/interactive.py
Orchestration
Central coordination, state, and domain-aware prompt assembly.
- Intelligence Manager · Central coordination layer that plans cycles, routes work, and assembles responses.
src/K2/aims_view/agents/intelligence_manager.py - Domain Knowledge · Insurance-specific business rules, patterns, and calculation knowledge.
src/K2/aims_view/core/domain_knowledge.py - Context Builder · Builds grounded prompt/context from domain knowledge and conversation state.
src/K2/aims_view/utils/context_builder.py - Memory Utils · Formats and persists conversation state for multi-turn reasoning.
src/K2/aims_view/utils/memory_utils.py
Agents
Planning, schema, SQL, execution, analysis, and response generation.
- Planner · Chooses the overall strategy for answering the user.
src/K2/aims_view/agents/intelligence/strategic_planner.py - Schema Analyst · Inspects database structure and relevant entities.
src/K2/aims_view/agents/intelligence/schema_analyst.py - Query Architect · Designs the SQL query plan from the user request and schema.
src/K2/aims_view/agents/intelligence/query_architect.py - Execution Specialist · Runs the query through the database layer and captures results.
src/K2/aims_view/agents/intelligence/execution_specialist.py - Computational Analyst · Performs calculations and derived analytics on retrieved data.
src/K2/aims_view/agents/intelligence/computational_analyst.py - Results Evaluator · Checks output quality, completeness, and answer fitness.
src/K2/aims_view/agents/intelligence/results_evaluator.py - Response Generator · Turns validated results into the final natural-language answer.
src/K2/aims_view/agents/intelligence/response_generator.py - Name Detector · Detects customer or person names in user input.
src/K2/aims_view/agents/specialized/name_detector.py - Customer Validator · Validates mentions against known customer records.
src/K2/aims_view/agents/specialized/customer_validator.py - Name Matcher · Resolves name variants to the most likely insurance customer entity.
src/K2/aims_view/agents/specialized/name_matcher.py
Infra
Model access, database connectivity, security, and persistence.
- LLM Factory · Creates and configures Gemini and Groq model clients with streaming support.
src/K2/aims_view/ai/llm_factory.py - Oracle DB · Oracle connection and query execution boundary for business data access.
src/K2/aims_view/database/database.py - SSL Config · Enterprise SSL-bypass and connection security settings.
src/K2/aims_view/security/ssl_config.py - Config · System settings for models, cycles, thresholds, agents, and database behavior.
src/K2/aims_view/config.json - Conversation Memory · Persistent conversation history for follow-up questions and continuity.
src/K2/aims_view/memory/conversation_memory.json
Connections 24
- Web App → Chat UI: serves · The web entrypoint presents the chat interface.
- Chat JS → Intelligence Manager: sends prompts · Browser interactions invoke the core orchestration layer.
- CLI Main → Interactive: launches · The CLI entry delegates to the interactive runner.
- Interactive → Intelligence Manager: invokes · Interactive sessions call the same orchestration core.
- Intelligence Manager → Context Builder: builds context · Coordinates grounded context for reasoning and response generation.
- Context Builder → Domain Knowledge: uses · Domain knowledge is injected into prompt/context construction.
- Intelligence Manager → Memory Utils: reads/writes · Conversation state is loaded and persisted across turns.
- Memory Utils → Conversation Memory: stores · Persistent session history backing multi-turn conversations.
- Intelligence Manager → Planner: starts with · The manager begins the reasoning cycle with strategic planning.
- Planner → Name Detector: checks entities · Customer-name detection can pre-process user requests.
- Name Detector → Customer Validator: validates · Detected names are checked against customer records.
- Customer Validator → Name Matcher: resolves · Matching disambiguates customer identity.
- Planner → Schema Analyst: routes to · The plan may require schema inspection.
- Schema Analyst → Query Architect: informs · Schema findings guide SQL design.
- Query Architect → Execution Specialist: executes via · Designed queries are handed to execution.
- Execution Specialist → Oracle DB: queries · Database access is isolated in the Oracle layer.
- Execution Specialist → Computational Analyst: passes results · Retrieved rows feed computational analysis.
- Computational Analyst → Results Evaluator: reviews · Derived results are checked for quality and sufficiency.
- Results Evaluator → Response Generator: finalizes · Validated output is converted into the response.
- Intelligence Manager → LLM Factory: uses models · Agent calls are mediated by the model factory.
- LLM Factory → Config: reads settings · Model selection and runtime behavior come from configuration.
- Oracle DB → SSL Config: secures · Connection behavior is shaped by SSL settings.
- Intelligence Manager → Config: reads settings · Execution thresholds and agent behavior come from config.
- Chat JS → Response Generator: renders · Streaming or final responses are shown in the UI.