{"id":49861705,"url":"https://github.com/ayoisio/adk-code-review-assistant","last_synced_at":"2026-05-14T21:43:36.998Z","repository":{"id":317505558,"uuid":"1055466121","full_name":"ayoisio/adk-code-review-assistant","owner":"ayoisio","description":"Code Review Assistant","archived":false,"fork":false,"pushed_at":"2025-10-01T10:05:59.000Z","size":126,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T11:12:36.597Z","etag":null,"topics":["adk","adk-python","code-generation","google-cloud","test-automation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayoisio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-12T09:59:21.000Z","updated_at":"2025-10-01T07:41:24.000Z","dependencies_parsed_at":"2025-10-01T11:12:50.776Z","dependency_job_id":"985a5668-24b2-4d2d-afe8-cdfcb3914b4a","html_url":"https://github.com/ayoisio/adk-code-review-assistant","commit_stats":null,"previous_names":["ayoisio/adk-code-review-assistant"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ayoisio/adk-code-review-assistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoisio%2Fadk-code-review-assistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoisio%2Fadk-code-review-assistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoisio%2Fadk-code-review-assistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoisio%2Fadk-code-review-assistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayoisio","download_url":"https://codeload.github.com/ayoisio/adk-code-review-assistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayoisio%2Fadk-code-review-assistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33044955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adk","adk-python","code-generation","google-cloud","test-automation"],"created_at":"2026-05-14T21:43:34.996Z","updated_at":"2026-05-14T21:43:36.986Z","avatar_url":"https://github.com/ayoisio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎓 Code Review Assistant\n\nAn intelligent, multi-agent code review system powered by Google ADK and Gemini models. This assistant provides comprehensive Python code analysis including structure evaluation, PEP 8 style checking, automated testing, personalized feedback with improvement tracking, and automated code fixing through iterative refinement.\n\n![Python](https://img.shields.io/badge/Python-3.10%2B-blue)\n![ADK](https://img.shields.io/badge/Google%20ADK-1.15%2B-green)\n![Gemini](https://img.shields.io/badge/Gemini-2.5-red)\n![License](https://img.shields.io/badge/License-MIT-yellow)\n\n## 🌟 Features\n\n### Core Capabilities\n- **Code Structure Analysis**: Parse and analyze Python code structure using AST, identifying functions, classes, imports, and structural issues\n- **PEP 8 Style Checking**: Validate code against Python style guidelines with detailed violation reports and weighted scoring\n- **Automated Testing**: Generate and execute comprehensive test cases (15-20 per submission) using built-in code execution\n- **Personalized Feedback**: Provide constructive, encouraging feedback that adapts based on submission history\n- **Automated Code Fixing**: Iteratively fix identified issues through a loop architecture with validation\n- **Progress Tracking**: Monitor improvement over time with persistent grading history\n- **Multi-Attempt Support**: Allow multiple submission attempts with incremental guidance\n\n### Technical Features\n- Dual-pipeline architecture (Review + Fix) using Sequential and Loop agents\n- Configurable LLM models (Gemini 2.5 Flash for tasks, Gemini 2.5 Pro for complex reasoning)\n- Session persistence with Vertex AI managed sessions or custom backends\n- Artifact management for reports and feedback history\n- Production deployment support for Agent Engine, Cloud Run, and GKE\n- Built-in observability with Cloud Trace integration\n\n## 🏛️ Architecture\n\nThe Code Review Assistant uses a sophisticated dual-pipeline architecture with specialized agents:\n\n```mermaid\ngraph TB\n    User[User Submits Python Code]\n    \n    subgraph Root[\"CodeReviewAssistant (Root Agent)\"]\n        Router[Request Router]\n    end\n    \n    subgraph ReviewPipeline[\"Review Pipeline (SequentialAgent)\"]\n        Analyzer[Code Analyzer\u003cbr/\u003eGemini 2.5 Flash\u003cbr/\u003eTool: analyze_code_structure]\n        StyleChecker[Style Checker\u003cbr/\u003eGemini 2.5 Flash\u003cbr/\u003eTool: check_code_style]\n        TestRunner[Test Runner\u003cbr/\u003eGemini 2.5 Pro\u003cbr/\u003eBuilt-in Code Executor]\n        Synthesizer[Feedback Synthesizer\u003cbr/\u003eGemini 2.5 Pro\u003cbr/\u003eTools: search_past_feedback,\u003cbr/\u003eupdate_grading_progress,\u003cbr/\u003esave_grading_report]\n        \n        Analyzer --\u003e StyleChecker\n        StyleChecker --\u003e TestRunner\n        TestRunner --\u003e Synthesizer\n    end\n    \n    subgraph FixPipeline[\"Fix Pipeline (SequentialAgent)\"]\n        subgraph FixLoop[\"Fix Attempt Loop (LoopAgent, max 3 iterations)\"]\n            Fixer[Code Fixer\u003cbr/\u003eGemini 2.5 Flash\u003cbr/\u003eGenerates corrected code]\n            FixTester[Fix Test Runner\u003cbr/\u003eGemini 2.5 Pro\u003cbr/\u003eValidates with tests]\n            Validator[Fix Validator\u003cbr/\u003eGemini 2.5 Flash\u003cbr/\u003eTools: validate_fixed_style,\u003cbr/\u003ecompile_fix_report,\u003cbr/\u003eexit_fix_loop]\n            \n            Fixer --\u003e FixTester\n            FixTester --\u003e Validator\n            Validator --\u003e|Not Successful| Fixer\n            Validator --\u003e|Successful\u003cbr/\u003eescalate=True| FixSynth\n        end\n        \n        FixSynth[Fix Synthesizer\u003cbr/\u003eGemini 2.5 Pro\u003cbr/\u003eTool: save_fix_report\u003cbr/\u003ePresents final results]\n    end\n    \n    subgraph State[\"State Management\"]\n        SessionState[(Session State\u003cbr/\u003eCODE_TO_REVIEW\u003cbr/\u003eSTYLE_SCORE\u003cbr/\u003eTEST_RESULTS\u003cbr/\u003eCODE_FIXES\u003cbr/\u003eFIX_STATUS)]\n        UserState[(User State\u003cbr/\u003eTOTAL_SUBMISSIONS\u003cbr/\u003eLAST_STYLE_SCORE\u003cbr/\u003ePAST_FEEDBACK)]\n    end\n    \n    User --\u003e Router\n    Router --\u003e Analyzer\n    Synthesizer --\u003e|Offers Fix| User\n    User --\u003e|Accepts Fix| Fixer\n    FixSynth --\u003e User\n    \n    Analyzer -.-\u003e|writes| SessionState\n    StyleChecker -.-\u003e|writes| SessionState\n    TestRunner -.-\u003e|writes| SessionState\n    Synthesizer -.-\u003e|reads/writes| SessionState\n    Synthesizer -.-\u003e|reads/writes| UserState\n    Fixer -.-\u003e|reads/writes| SessionState\n    FixTester -.-\u003e|reads/writes| SessionState\n    Validator -.-\u003e|reads/writes| SessionState\n    \n    style User fill:#e1f5fe\n    style Router fill:#fff3e0\n    style Analyzer fill:#e8f5e9\n    style StyleChecker fill:#e8f5e9\n    style TestRunner fill:#f3e5f5\n    style Synthesizer fill:#f3e5f5\n    style Fixer fill:#e8f5e9\n    style FixTester fill:#f3e5f5\n    style Validator fill:#e8f5e9\n    style FixSynth fill:#f3e5f5\n    style SessionState fill:#fce4ec\n    style UserState fill:#fce4ec\n```\n\n### Architecture Components\n\n#### **Main Orchestrator**\n- **CodeReviewAssistant**: Entry point that routes user input to appropriate pipeline\n- Delegates to **CodeReviewPipeline** for initial analysis\n- Offers **CodeFixPipeline** if issues are identified\n- Manages overall session state and user interaction\n\n#### **Review Pipeline (SequentialAgent)**\n\nAnalyzes code through four specialized agents in sequence:\n\n1. **Code Analyzer Agent** (Gemini 2.5 Flash)\n   - Uses `analyze_code_structure()` tool\n   - Parses Python code using AST\n   - Identifies functions, classes, imports, docstrings\n   - Calculates complexity metrics\n   - Stores analysis in session state\n   \n2. **Style Checker Agent** (Gemini 2.5 Flash)\n   - Uses `check_code_style()` tool\n   - Validates PEP 8 compliance via pycodestyle\n   - Checks naming conventions\n   - Calculates weighted style score (0-100)\n   - Reports violations with line numbers\n   \n3. **Test Runner Agent** (Gemini 2.5 Pro)\n   - Uses built-in code executor\n   - Generates 15-20 comprehensive test cases\n   - Executes tests in sandboxed environment\n   - Returns structured JSON results\n   - Identifies critical issues vs expected behavior\n   \n4. **Feedback Synthesizer Agent** (Gemini 2.5 Pro)\n   - Uses `search_past_feedback()` tool for history\n   - Uses `update_grading_progress()` for metrics\n   - Uses `save_grading_report()` for artifacts\n   - Combines all analysis results\n   - Generates personalized, educational feedback\n   - Tracks improvement over time\n\n#### **Fix Pipeline (SequentialAgent + LoopAgent)**\n\nAutomatically fixes identified issues through iterative refinement:\n\n**FixAttemptLoop** (LoopAgent, max 3 iterations):\n1. **Code Fixer Agent** (Gemini 2.5 Flash)\n   - Generates corrected Python code\n   - Addresses style violations, bugs, and logic errors\n   - Outputs raw Python (no markdown)\n   \n2. **Fix Test Runner Agent** (Gemini 2.5 Pro)\n   - Executes same tests on fixed code\n   - Returns structured JSON with pass/fail metrics\n   - Compares results to original baseline\n   \n3. **Fix Validator Agent** (Gemini 2.5 Flash)\n   - Uses `validate_fixed_style()` tool\n   - Uses `compile_fix_report()` tool\n   - Determines fix status: SUCCESSFUL/PARTIAL/FAILED\n   - Calls `exit_fix_loop()` if successful (sets escalate=True)\n   - Otherwise, loop continues for another iteration\n\n**Fix Synthesizer Agent** (Gemini 2.5 Pro):\n- Runs once after loop completes\n- Uses `save_fix_report()` tool\n- Presents final fix results with before/after comparison\n- Provides educational explanations of changes\n- Shows complete corrected code\n\n#### **Tool Functions**\n\n**Review Pipeline Tools:**\n- `analyze_code_structure(code, tool_context)`: AST-based code parsing and metrics\n- `check_code_style(code, tool_context)`: pycodestyle integration with weighted scoring\n- `search_past_feedback(developer_id, tool_context)`: Historical feedback retrieval from memory\n- `update_grading_progress(tool_context)`: Progress tracking across session/user/lifetime tiers\n- `save_grading_report(feedback_text, tool_context)`: Artifact generation for reports\n\n**Fix Pipeline Tools:**\n- `validate_fixed_style(tool_context)`: Style validation for corrected code\n- `compile_fix_report(tool_context)`: Comprehensive fix attempt analysis\n- `exit_fix_loop(tool_context)`: Loop exit signal (sets escalate=True)\n- `save_fix_report(tool_context)`: Fix artifact generation\n\n#### **State Management**\n\n- **Session State**: Temporary data for current review (CODE_TO_REVIEW, STYLE_SCORE, TEST_RESULTS)\n- **User State**: Persistent history (USER_TOTAL_SUBMISSIONS, USER_LAST_STYLE_SCORE)\n- **StateKeys Constants**: Type-safe state access pattern prevents typos\n- **Artifact Storage**: JSON reports saved via Vertex AI artifact service or GCS\n\n## 📋 Prerequisites\n\n- Python 3.10 or higher\n- Google Cloud Project with billing enabled\n- `gcloud` CLI installed and authenticated\n- Git for version control\n\n## 🚀 Quick Start\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/ayoisio/code-review-assistant.git\ncd code-review-assistant\n```\n\n### 2. Set Up Environment\n\n```bash\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install dependencies\npip install -r code_review_assistant/requirements.txt\n```\n\n### 3. Configure Environment Variables\n\n```bash\n# Copy the example environment file\ncp .env.example .env\n\n# Edit .env with your settings\nnano .env  # or use your preferred editor\n```\n\nRequired configuration:\n```bash\nGOOGLE_CLOUD_PROJECT=your-project-id\nGOOGLE_CLOUD_LOCATION=us-central1\nGOOGLE_GENAI_USE_VERTEXAI=true\n```\n\n### 4. Run the Assistant Locally\n\n```bash\n# Run with in-memory sessions (development)\n./deploy.sh local\n```\n\nNavigate to `http://localhost:8080` in your browser.\n\n## 🏗️ Project Structure\n\n```\ncode-review-assistant/\n├── code_review_assistant/\n│   ├── __init__.py\n│   ├── agent.py                 # Main orchestration (root agent + pipelines)\n│   ├── config.py                # Configuration management\n│   ├── constants.py             # StateKeys constants\n│   ├── tools.py                 # Tool implementations\n│   └── sub_agents/\n│       ├── review_pipeline/\n│       │   ├── __init__.py\n│       │   ├── code_analyzer.py\n│       │   ├── style_checker.py\n│       │   ├── test_runner.py\n│       │   └── feedback_synthesizer.py\n│       └── fix_pipeline/\n│           ├── __init__.py\n│           ├── code_fixer.py\n│           ├── fix_test_runner.py\n│           ├── fix_validator.py\n│           └── fix_synthesizer.py\n├── tests/\n│   ├── test_agent_engine.py     # Agent Engine deployment test\n│   └── ...\n├── deploy.sh                     # Unified deployment script\n├── .env.example                  # Environment variable template\n├── requirements.txt              # Python dependencies\n└── README.md                     # This file\n```\n\n## 🔧 Configuration\n\n### Model Selection\n\nThe assistant uses two Gemini models configured in `config.py`:\n\n```python\n# Fast model for mechanical tasks (analysis, style checking, fixing)\nworker_model = \"gemini-2.5-flash\"\n\n# Advanced model for complex reasoning (testing, synthesis)\ncritic_model = \"gemini-2.5-pro\"\n```\n\n### Session Management\n\nAgent Engine deployments use Vertex AI managed sessions automatically. For local development or Cloud Run, configure in `.env`:\n\n```bash\n# Local development (in-memory, ephemeral)\n# No SESSION_SERVICE_URI needed - handled by deploy.sh\n\n# Cloud Run (PostgreSQL via Cloud SQL)\n# Automatically configured by deploy.sh\n```\n\n## 🎯 Usage Examples\n\n### Basic Code Review\n\nSubmit code through the web interface or API:\n\n```python\ndef calculate_average(numbers):\n    total = 0\n    for num in numbers:\n        total += num\n    return total / len(numbers)\n```\n\nThe assistant will:\n1. Analyze structure (1 function, no classes)\n2. Check PEP 8 compliance (score: 85/100 - missing docstring)\n3. Generate and run 15-20 tests (finds edge case: crashes on empty list)\n4. Provide comprehensive feedback with specific improvements\n\n### Automated Fixing\n\nAfter receiving review feedback, user responds \"yes\" when offered fixes. The fix pipeline will:\n\n1. **Iteration 1**: Add docstring, fix edge case → tests: 18/20 passed\n2. **Iteration 2**: Fix remaining edge cases → tests: 20/20 passed, style: 100/100\n3. **Exit**: Escalate triggered, synthesizer presents final corrected code\n\n### API Usage\n\n```python\nimport requests\n\n# Submit code for review\nresponse = requests.post(\n    \"http://localhost:8080/run_sse\",\n    json={\n        \"app_name\": \"code_review_assistant\",\n        \"user_id\": \"developer_001\",\n        \"session_id\": None,  # Auto-creates new session\n        \"new_message\": {\n            \"role\": \"user\",\n            \"parts\": [{\"text\": \"Review this code:\\n\\ndef add(a,b):return a+b\"}]\n        },\n        \"streaming\": False\n    }\n)\n\nprint(response.json())\n```\n\n## 🚢 Deployment\n\nThe unified `deploy.sh` script handles all deployment scenarios:\n\n### Local Development\n\n```bash\n# Run with in-memory sessions and hot reload\n./deploy.sh local\n```\n\n### Cloud Run (Serverless with Persistence)\n\n```bash\n# Deploy with Cloud SQL for session persistence\n./deploy.sh cloud-run\n```\n\nWhat the script handles automatically:\n- Enables required APIs (Cloud Run, Cloud SQL, Cloud Build, etc.)\n- Creates Cloud SQL instance if not exists\n- Generates secure database credentials\n- Sets up IAM permissions\n- Deploys with ADK CLI\n- Configures Cloud SQL connection\n\n### Vertex AI Agent Engine (Fully Managed)\n\n```bash\n# Deploy to Agent Engine with managed sessions\n./deploy.sh agent-engine\n```\n\nWhat the script handles automatically:\n- Enables required APIs (AI Platform, Storage, Cloud Trace)\n- Creates staging and artifact buckets\n- Sets up IAM permissions\n- Deploys with ADK CLI and trace-to-cloud flag\n- Returns Agent Engine ID for future updates\n\nSave the returned Agent Engine ID in `.env`:\n```bash\nAGENT_ENGINE_ID=7917477678498709504\n```\n\n### Testing Deployed Agent\n\n```bash\n# Test Agent Engine deployment\npython tests/test_agent_engine.py\n```\n\n## 🧪 Testing\n\n### Manual Testing\n\nUse the sample buggy code to test the complete review + fix flow:\n\n```python\ndef dfs(graph, start):\n    \"\"\"Performs depth-first search on a graph.\"\"\"\n    visited = set()\n    stack = start  # Bug: should be [start]\n    \n    while stack:\n        current = stack.pop()\n        if current not in visited:\n            visited.add(current)\n            stack.extend(graph[current])  # Bug: KeyError if key missing\n    \n    return visited\n```\n\nExpected behavior:\n1. Review pipeline identifies: AttributeError (can't .pop() on string), potential KeyError\n2. Offer to fix\n3. Fix loop corrects both issues in 1-2 iterations\n4. Final code passes all tests with 100/100 style score\n\n## 📊 Monitoring and Observability\n\n### Cloud Trace Integration\n\nWhen deployed with `--trace-to-cloud`, every request generates detailed traces showing:\n\n- Complete request timeline from input to response\n- Individual agent executions with durations\n- Tool function calls with inputs/outputs\n- LLM requests with token counts\n- Loop iterations in fix pipeline\n- State operations (read/write)\n\nAccess traces:\n1. Navigate to [Cloud Trace Explorer](https://console.cloud.google.com/traces)\n2. Select your project\n3. Click on traces to view waterfall charts\n\n### View Logs\n\n```bash\n# Agent Engine logs\ngcloud logging read \"resource.type=aiplatform.googleapis.com/ReasoningEngine \\\n    AND resource.labels.reasoning_engine_id=$AGENT_ENGINE_ID\" \\\n    --limit=50\n\n# Cloud Run logs\ngcloud logging read \"resource.type=cloud_run_revision \\\n    AND resource.labels.service_name=code-review-assistant\" \\\n    --limit=50\n```\n\n## 📚 Additional Resources\n\n- [ADK Documentation](https://google.github.io/adk-docs/)\n- [Agent Engine Guide](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview)\n- [Cloud Run Documentation](https://cloud.google.com/run/docs)\n- [Cloud Trace Documentation](https://cloud.google.com/trace/docs)\n\n---\n\nBuilt with ❤️ using Google ADK and Gemini\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayoisio%2Fadk-code-review-assistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayoisio%2Fadk-code-review-assistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayoisio%2Fadk-code-review-assistant/lists"}