🚀 Git-Dev-Concierge: Autonomous Software Development Concierge

An intelligent, context-aware agentic workspace that acts as a personal assistant for software developers. Git-Dev-Concierge bridges the gap between local version control state, codebase health auditing, personal developer schedules (Google Calendar), and academic paper compilation/literature review.

Built using Google's Agent Development Kit (ADK) and powered by the latest Gemini models, this project demonstrates a highly robust ReAct (Reasoning and Acting) paradigm that automates "developer janitorial tasks," code assessment, and research generation.

---

Demo: https://youtu.be/ulrXK9AMhLg

🏗️ System Architecture

graph TD
    User((Developer)) --> Playground[ADK Playground Interface]
    Playground --> Orchestrator[Research Agent Core / Orchestrator]
    
    subgraph "Core Services (Library)"
        Orchestrator --> CodeBroker[Code Broker]
        Orchestrator --> ResearchGen[Research Generator Service]
    end
    
    subgraph "Backends & Tools"
        CodeBroker --> AssessmentTools[Assessment Tools]
        ResearchGen --> DataReaders[Data Readers]
        ResearchGen --> Plotter[Plotter]
        ResearchGen --> Models[LLM/Research Models]
        ResearchGen --> Formatter[Formatter/Compiler]
    end
    
    Orchestrator --> Gemini[Gemini LLM Models]
    
    subgraph "Persistent Storage"
        Orchestrator --> SessionDB[(Session DB)]
        DataReaders --> Repo[(Code Repositories)]
        DataReaders --> Notes[(Project Notes)]
        Formatter --> Outputs[/PDF/LaTeX Outputs/]
    end

Loading

---

🌟 Key Features

📅 Temporal & Schedule Correlation

• Calendar Integration: Connects securely to the Google Calendar API to fetch the developer’s upcoming meetings and events.
• Smart Event Scheduling: Automatically books focused "code blocks," preparation time for code reviews, and testing slots directly on the calendar based on uncommitted repository tasks.

🕵️ Code Broker (code_broker)

• Automated Code Auditing: Performs deep, automated audits of local directories, standalone source files, or remote repositories.
• Vulnerability & Architecture Mapping: Evaluates codebase security, structure, and quality, generating comprehensive, interactive Markdown and browser-viewable HTML reports.

🔬 Dynamic Academic Research Generator (research_generator)

• Repository & Note Ingestion: Parses project notes, diaries, repository codebases, and Jupyter notebooks (.ipynb) to build a high-fidelity context.
• Section-by-Section Drafting: Leverages specialized Gemini models to generate the Abstract, Introduction, Related Work, Methodology, Results, and Conclusions.
• Automatic Plotting: Programmatically generates polished plots based on repository and project history.
• LaTeX Compilation: Auto-formats a professional two-column paper using the official arXiv template and compiles it into a production-grade PDF using the system’s pdflatex backend.

🔄 Local Git State Tracker

• Real-time Status Syncing: Automatically reads uncommitted changes and branch states to prioritize development tasks.

---

📂 Repository Structure

The project is structured into modular subsystems:

Intensive-Vibe-Coding-Capstone-Project/
├── docs/                        # Project documentation & notes
│   ├── agent_schematic.md       # Diagram of agent architecture
│   ├── concierge_agent_proposals.md # Initial proposals & ideation
│   ├── kaggle_writeup.md        # Kaggle integration details
│   ├── notes.txt                # Everyday development history diary
│   └── research_paper/          # Source LaTeX files for the core paper
├── git-dev-concierge/           # Primary ADK agent workspace
│   ├── app/                     # Main agent codebase
│   │   ├── agent.py             # Agent initialization & tool definition
│   │   ├── code_broker.py       # Code Broker tool bridge
│   │   ├── fast_api_app.py      # FastAPI application wrapper
│   │   ├── github_tools.py      # Local/remote Git and GitHub interaction utilities
│   │   ├── gitlab_tools.py      # GitLab API file and repo integration
│   │   └── research_generator_tool.py # LaTeX paper compiler integration
│   ├── code_broker/             # Independent automated code health subsystem
│   │   ├── agents.py            # ReAct agent for codebase assessments
│   │   ├── config.py            # Model configs
│   │   ├── main.py              # Broker CLI entry point
│   │   └── report.py            # HTML template compiler and reporter
│   ├── research_generator/      # System for programmatically building papers
│   │   ├── formatter.py         # LaTeX generator and pdflatex compiler wrapper
│   │   ├── main.py              # Generator pipeline orchestrator
│   │   ├── models.py            # Task-specific Gemini models (Drafting/Formatting)
│   │   ├── plotter.py           # Procedural visualization generator
│   │   └── readers.py           # Parses code, Jupyter notebooks, & logs
│   ├── templates/               # LaTeX style files and BibTeX references
│   ├── reports/                 # Output directories for generated PDFs & reports
│   ├── credentials.json         # Google Developer Console API credentials
│   ├── pyproject.toml           # Complete workspace dependencies and linter configuration
│   └── requirements.txt         # Auto-generated requirements specification
├── tests/                       # Root-level integration and pipeline tests
│   └── test_research_pipeline.py# Unit tests verifying file ingestion and drafting
└── test_model_quota.py          # API rate-limit and quota verification utility

---

🛠️ Requirements & Setup

Prerequisites

1. Python: 3.11 to 3.13 (managed via uv).
2. uv: Recommended Python package manager. Install with:

   curl -LsSf https://astral.sh/uv/install.sh | sh

3. LaTeX: Ensure pdflatex is installed on your system (for compiling research papers):

   sudo apt-get install texlive-latex-base texlive-fonts-recommended texlive-latex-extra

4. Google Cloud SDK: Recommended for authentication with Vertex AI and other services.

Authentication Configuration

The temporal correlation functions require Google Calendar API access.

1. Obtain an OAuth 2.0 client credential JSON from the Google Cloud Console.
2. Place this file inside the git-dev-concierge folder named as credentials.json.
3. The first time the calendar tool runs, an authorization flow will open in your browser to generate the local token.json session file.

---

⚡ Quick Start

1. Install Dependencies

Initialize the project environment and download dependencies using agents-cli:

cd git-dev-concierge
uv tool install google-agents-cli
agents-cli install

2. Run the Interactive Agent Playground

Launch a local web interface to interact with your developer focus concierge:

agents-cli playground

Once active, navigate to the local browser address provided to test queries like:

"Scan my repository and plan a schedule slot for my uncommitted work on the calendar."

3. Run the Code Broker (Code Auditing CLI)

You can directly run the independent code assessment engine to audit local files or directories:

# Audit a specific directory
uv run -m git-dev-concierge.code_broker.main ./git-dev-concierge/app/

This generates and displays an interactive md / html audit report highlighting file layout, style guide compliance, and suggestions.

---

🧪 Testing & Validation

Maintain codebase integrity and verify behavior across all layers with the built-in testing framework:

Root Pipeline Tests

To verify the research pipeline (reading notebooks, parsing source files, formatting sections):

# Run tests from the root directory
uv run python -m unittest tests/test_research_pipeline.py

Agent Workspace Tests

Run unit and integration tests inside the concierge workspace:

cd git-dev-concierge
uv run pytest tests/unit tests/integration

Run ADK Evaluations

Perform high-fidelity model evaluations, clustering of failures, and prompt auto-tuning:

# Run agent on datasets and evaluate metrics
agents-cli eval generate
agents-cli eval grade

---

📚 Technical Standards & Practices

This repository complies strictly with professional software engineering practices:

• Ecosystem Tools: Auto-formatting is governed by ruff, and types are managed via ty configuration in pyproject.toml.
• Math & Tabular Data: Mathematical operations are designed using JAX, and tabular datasets use the high-performance Polars library rather than pandas/numpy.
• Google Style Guide: All code matches standard Python naming conventions and contains strict Google-style Docstrings.