Add FastAPI backend HMVC module structure

[NoorChasib]

🎯 Summary

ZUBA-423

This PR transforms the backend architecture to use HMVC pattern while integrating FastMCP for agent-based interactions.

Key Changes

1. HMVC Module Structure

• Modular Organization: Split functionality into self-contained modules (agent/, analytics/, auth/, chat/, feedback/)
• Module Registry: Added centralized module discovery and registration system
• Clean Separation: Each module contains its own controllers/, models/, services/, and views/

2. FastMCP Agent Integration

Agent Registry System

• app/modules/agent/agents/__init__.py: Central registry for MCP agents with auto-discovery
• Agent Mounting: Combines multiple specialized agents into a unified MCP server
• Capability Mapping: Maps agent capabilities to specific tasks (e.g., "search" → semantic_search, explicit_search)

Specialized MCP Agents

• Semantic Search: agents/search/semantic_search.py - Vector similarity search
• Explicit Search: agents/search/explicit_search.py - Cypher query execution
• Community Detection: agents/search/community_detection.py - Graph analysis
• Orchestrator: agents/orchestrator/orchestrator_agent.py - Multi-agent coordination

Service Layer Integration

• AgentService: Handles authenticated MCP client connections and tool execution
• OrchestratorService: Manages complex multi-agent workflows
• Azure AI Integration: Routes tool calls through Azure OpenAI with proper authentication

3. Technical Implementation

MCP Client Pattern

# Combined MCP server with all agents
combined_mcp = agent_registry.get_combined_mcp()
client = Client(combined_mcp)
async with client:
    tools = await client.list_tools()
    result = await client.call_tool(tool_name, arguments)

Authentication Flow

• MCP servers accessed through authenticated service layer
• Azure AI handles LLM interactions with tool calling
• Proper error handling for tool execution failures

Tool Discovery & Execution

• Dynamic tool registration from mounted agents
• Tool name prefixing for namespace separation (e.g., semanticsearch_semantic_search)
• Automatic tool selection based on user queries

4. API Endpoints

New Routes

• POST /agent/ - Basic agent chat with automatic tool selection
• POST /agent/orchestrate/ - Complex multi-agent task coordination
• GET /agent/capabilities/ - List available agents and capabilities
• GET /agent/status/{agent_name} - Individual agent status

Files Modified/Added

Core Architecture

• app/modules/module_registry.py - Module discovery system
• app/modules/agent/ - Complete agent module with HMVC structure

FastMCP Integration

• app/modules/agent/agents/__init__.py - Agent registry
• app/modules/agent/agents/search/ - Search agent implementations
• app/modules/agent/agents/orchestrator/ - Multi-agent orchestration
• app/modules/agent/services/agent_service.py - MCP client integration
• app/modules/agent/services/orchestrator_service.py - Orchestration logic

🔰 Checklist

• I have read and agree with the following checklist

• I have performed a self-review of my code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation where required.
• I have tested my changes to the best of my ability.
• I have consulted with the team if introducing a new dependency.

[dbarkowsky]

Everywhere this symbol occurs, there's a new line missing.

[dbarkowsky]

It looks like this shares a lot of logic with the agent_service.py
I wonder if we could make a parent class that covers both of these.

[dbarkowsky]

Are these for future outside use of this API?
Otherwise traffic from the browser doesn't perform the login through this API at the moment.

[dbarkowsky]

Tested routes available via Swagger docs.
Everything seems to be working with the understanding that some items are WIP.

A few items to edit at your own judgement:

• The auth routes don't have a current purpose, as authentication is handled elsewhere. Unless we're planning on changing this more. I would suggest leaving it as is. Edit: I'm seeing now these were in the old controllers as well. I'm still convinced the frontend never calls them though.
• If the "view" portion of each module isn't used, maybe we don't need them.
• It might be simpler to combine the three search mcp servers into a single one with three tools.

Let me know when you're done any edits you want to make and I can approve.
Only one I'm hung up on is the lack of new lines in files. Might we worth setting your IDE to do that automatically.