AgentsStudio

An advanced, Web-based application for comprehensive code analysis. This platform orchestrates a team of specialized Large Language Model (LLM) agents to provide deep, structured, and actionable feedback on code quality, security, performance, and architecture.

Built with a Python (Flask) backend for orchestration and a single-page application (SPA) frontend for a responsive, desktop-like user experience.

---

Core Concept: Structured Agentic Analysis

The primary goal is to move beyond simple keyword-based analysis by enforcing a structured analysis output. The system uses Pydantic to strictly constrain the LLMs, forcing them to produce reliable, machine-readable JSON reports.

This structured approach ensures:

• Reliability: Reports are guaranteed to match a defined schema, making them easy for the frontend to consume.
• Actionability: Every finding includes specific fields like severity, issue_type, and line number.
• Depth: All analysis reports inherit from BaseLLMResponse, which requires a highly detailed, Markdown-formatted MarkdownDescription field, ensuring every result comes with a comprehensive, human-readable explanation.

---

Features: The Specialized Agent Suite

The platform employs a robust system of nine specialized LLM agents, each strictly constrained by its unique system_prompt and Pydantic schema to deliver reliable, structured reports.

Category	Agent Name	Core Focus Area	Output Schema	System Prompt Focus
Foundation	Summarizer	High-level, neutral explanation of the code's purpose and component roles.	SummaryResponse	Neutrality, Clarity, Functionality.
Static Analysis	Code Smell	Identifies anti-patterns: Long Methods, Magic Numbers, Poor Naming, duplication.	CodeSmellReport	Maintainability, Readability, Refactoring Candidates.
	Complexity	Measures code difficulty using metrics like Cyclomatic Complexity and deep nesting.	ComplexityReport	Cognitive Load and Testability.
	Dependency	Flags unused imports, deprecated/outdated packages, and unpinned dependencies.	DependencyReport	Security, Stability, and Build Reliability.
Quality & Design	SOLID	Analyzes adherence to the fundamental SOLID object-oriented principles.	SolidReport	Interface segregation, Single Responsibility, Liskov Substitution.
	Architecture	Focuses on structural issues: Tight Coupling, Low Cohesion, Layer Violations, God Classes.	ArchitectureReport	Scalability, Modularity, and Extensibility.
	Refactor	Provides practical, human-friendly, and actionable suggestions for code improvement.	RefactorReport	Practical, Developer-friendly Code Improvements.
Risk & Performance	Security	Detects critical vulnerabilities: Injection, Hardcoded Secrets, Path Traversal, weak cryptography.	SecurityReport	Real-world exploitation, OWASP Top 10, Secure Coding Practices.
	Performance	Pinpoints runtime bottlenecks: O(n²) behavior, inefficient data structures, caching issues, blocking I/O.	PerformanceReport	Algorithmic Complexity, Runtime Efficiency, Resource Usage.

---

Architectural Deep Dive

Backend: Python (Flask & Orchestration)

The backend manages job state, file I/O, configuration, and coordinates the LLM calls.

• app.py: The main entry point. It sets up the Flask application and handles routing. Crucially, it integrates the Hybrid Threading Model to facilitate native file dialogs (see Key Technologies).
• analysis_orchestration.py: The Analysis Orchestrator. This class is the core of the analysis workflow:
  • Job Management: It starts and tracks batch analysis jobs, maintaining real-time status and progress.
  • Reliability: It enforces retry logic (default 3 attempts) for transient LLM errors or malformed JSON responses, ensuring high job completion rates.
  • Concurrency: It executes agents in a non-blocking, multi-threaded batch, allowing the UI to remain responsive during long-running LLM calls.
• base_agent.py: Defines the BaseAgent class from which all LLM agents inherit. It abstracts the pydantic-ai library, enforcing the system_prompt and output_type for every agent instance.
• llm_loader.py: An abstraction layer that resolves the correct LLM provider (e.g., Google, OpenAI, local Ollama) based on the centralized configuration in llm_config.yaml.

Frontend: Web Interface (SPA)

A fast, responsive Single-Page Application designed to feel like a desktop IDE, using vanilla JavaScript for efficiency.

• UI Components:
  • File Tree: Navigation sidebar for selecting files within the project root.
  • Code Editor: Resizable panel for viewing code.
  • Analysis Results: Tabbed view for displaying structured JSON reports and their corresponding MarkdownDescription.
  • Run Modal: Non-blocking modal for starting, tracking, and cancelling batch analysis jobs, featuring a real-time progress bar and log stream.
• Styling & Theme: Uses Tailwind CSS for utility-first styling and a custom VS Code-like dark theme (styles.css) for a familiar developer experience.
• State Management: store.js manages global variables (projectRoot, currentFile, agentResults) and provides data persistence across sessions.

---

Installation and Setup

Follow these steps to set up and run the Code Analysis Studio locally.

Prerequisites

• Python 3.9+
• A stable internet connection (for cloud LLM) or a local Ollama installation.
• A valid API Key for your chosen cloud LLM provider (e.g., Google Gemini).

1. Setup

Clone the repository and install dependencies.

# Clone the repository
git clone https://github.com/DeepActionPotential/AgentsStudio
cd multi-agent-ai-code-review

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate 

pip install -r requirements.txt 

2. Configuration

Set your LLM connection details and core analysis parameters.

1. LLM Provider: Configure your API access in src/config/llm_config.yaml.

   • Set default_llm_type: cloud and provide your api_key under the cloud section.
   • Alternatively, set default_llm_type: local and configure the id and base_url for your local Ollama instance. (Configuration updates can also be done via the settings.html UI).

2. Analysis Parameters: Review src/config/analysis_config.yaml for key limits:

   • max_file_size_kb: 300: The file size limit for LLM processing. file_loader.py enforces this check to prevent oversized API requests.
   • timeout.seconds: 40: The maximum time an individual agent is allowed to execute.

# analysis_config.yaml snippet
max_file_size_kb: 300
retry:
  attempts: 3
timeout:
  seconds: 40 

3. Run the Application

Start the Flask development server:

python app.py

The console will confirm the dual-thread startup:

🚀 Server running on http://127.0.0.1:5000 (Flask in background thread) Tk dialog handler running on the main thread. Press Ctrl+C to stop.

4. Usage

1. Open your browser and navigate to the local address (http://127.0.0.1:5000).

2. Click "Open Folder" to trigger the native OS folder dialog (handled by the main thread). Select your project root.

3. The File Tree will populate. Select files for analysis.

4. Run a Batch Analysis from the modal. Monitor the progress bar and real-time logs (Errors, Warnings, Success messages).

5. View results. Click on the tab for any file/agent combination to see the detailed JSON report and the associated MarkdownDescription.

---

5. Demo Images

Common Issues and Troubleshooting

Issue	Root Cause & Code Component	Solution
LLM Timeout	The LLM exceeded the configured timeout.seconds (default 40s) during a complex or large file analysis.	Increase timeout.seconds in analysis_config.yaml. Break up very large files or review code complexity.
Malformed JSON / Retry Failure	The LLM failed to produce output strictly conforming to the required Pydantic schema after all retry.attempts.	Try a higher-tier LLM (e.g., a "Pro" or "Turbo" model) known for better instruction following. Check the agent's system_prompt for clarity.
File Skipped	The file exceeded the max_file_size_kb limit (default 300KB) or had a disallowed extension.	Increase max_file_size_kb in analysis_config.yaml. The file_loader.py module enforces this.
Native Folder Dialog Not Appearing	This is typically a failure in the Hybrid Threading Model where the main process is blocked or the tkinter library is not fully functional on the system (e.g., in a non-GUI environment).	Ensure all tkinter dependencies are installed for your OS. If running headless, ensure you have a configured X-server (or use a remote desktop GUI).
Configuration Not Saving	Errors in updating llm_config.yaml from the Settings UI.	Verify that src/logic/utils/config_editor.py can correctly load/save the YAML without permission errors. The ruamel.yaml library is used to preserve file formatting.

---

Key Technologies

Hybrid Threading Model for Local File Access

The primary technical challenge of building a web application that needs to access the local file system (to load source code) is solved by this hybrid model.

• Limitation: A web browser cannot securely initiate a file dialog to read an arbitrary local directory path without user interaction.
• Solution: The application runs Flask (Web UI) in a background daemon thread and reserves the Main Thread for a hidden Tkinter instance.
• Workflow: When the user clicks "Open Folder" in the browser:
  1. The Flask endpoint receives the request.
  2. Flask places a message into a thread-safe queue.Queue.
  3. The main thread's handle_dialogs() function constantly listens to this queue.
  4. The main thread executes tkinter.filedialog.askdirectory(), which presents the native OS dialog.
  5. The selected path is returned via a different queue to the Flask thread, which then begins scanning and loading files.

LLM Integration and Structured Output

This platform relies heavily on the pydantic-ai library to guarantee output quality.

• Agent Constraint: Every LLM agent (e.g., SecurityAgent, PerformanceAgent) defines a Pydantic output_type.
• Model Guidance: The agent's system_prompt and the Pydantic schema are sent to the LLM, instructing it to produce a JSON object strictly conforming to that schema.
• Validation: If the LLM returns non-conforming JSON, the pydantic-ai validation fails, triggering the AnalysisOrchestrator's retry mechanism for reliability.