Replace Codebase Analysis with Code Upload and Prompt

[djaboxx]

Gemini Update Agent

Gemini Update Agent is a Python tool that combines codebase analysis and feature planning capabilities. It leverages Google's Gemini AI models to understand your project and help implement new features by analyzing your code and generating detailed implementation plans.

Features

• Codebase Analysis: Analyzes your codebase to understand its structure, dependencies, and architecture.
• Feature Specification: Generates detailed feature specifications from natural language descriptions.
• Implementation Planning: Creates step-by-step implementation plans for new features.
• Markdown Output: All outputs are saved as well-formatted markdown files.
• Gemini Files API Support: Leverages Gemini's Files API for enhanced codebase context, allowing analysis of larger codebases and supporting remote code.

Prerequisites

• Python 3.11+
• Google Gemini API Key (see Google AI Studio for setup).
• Key Libraries: This project relies on google.generativeai for AI interaction, pydantic for data validation, pydantic_ai for agent orchestration, jinja2 for prompt templating, rich for rich console output, and python-dotenv for environment variable management.

Installation

# Clone the repository
git clone https://github.com/your-organization/gemini-update.git
cd gemini-update

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Usage

Set Environment Variables

You can set environment variables directly:

export GEMINI_API_KEY="your_api_key_here"

Or copy the .env.example file to .env and edit it with your values:

cp .env.example .env
# Now edit .env with your API key and other settings

Analyze a Codebase

./gemini-update.py analyze --project-dir /path/to/your/project

Generate a Feature Specification and Implementation Plan

./gemini-update.py feature --project-dir /path/to/your/project --feature-description "Add dark mode support to the UI components"

Using Gemini Files API

Dave, as we discussed, you're using Gemini 2.5 Pro, which greatly enhances the "just upload files and prompt" approach. The GeminiFilesAPI integration is designed to leverage these large context window capabilities by uploading files to Gemini's backend, allowing the model to access a substantial portion of your codebase directly.

To leverage the Gemini Files API for improved codebase analysis:

# For codebase analysis
./gemini-update.py analyze --project-dir /path/to/your/project --use-gemini-files

# For feature planning
./gemini-update.py feature --project-dir /path/to/your/project --feature-description "Your feature description" --use-gemini-files

Using the Gemini Files API enables:

• More reliable code context for the AI model, as the model can directly access uploaded file content as Blob objects.
• Support for analyzing codebases hosted on remote systems (though local files are still read for upload).
• Consistent file handling across different environments.

File Size Limits

By default, files up to 4MB can be uploaded to the Gemini Files API. You can adjust this limit:

./gemini-update.py feature --project-dir /path/to/your/project --feature-description "..." --use-gemini-files --max-file-size 6.0

Command Options

usage: gemini-update.py [-h] {analyze,feature,version} ...

Gemini Update - Analyze codebases and plan feature implementations

positional arguments:
  {analyze,feature,version}
                        Command to run
    analyze             Analyze a codebase
    feature             Generate a feature specification and implementation plan
    version             Show version information

options:
  -h, --help            show this help message and exit

Docker Usage

You can also run Gemini Update Agent in a Docker container:

Building the Docker Image

docker build -t gemini-update .

Using the Docker Image

# Analyze a codebase
docker run --rm \
  -v /path/to/your/project:/workspace:ro \
  -v /path/to/output:/output \
  -e GEMINI_API_KEY="your_api_key_here" \
  gemini-update analyze --project-dir /workspace

# Generate a feature plan
docker run --rm \
  -v /path/to/your/project:/workspace:ro \
  -v /path/to/output:/output \
  -e GEMINI_API_KEY="your_api_key_here" \
  gemini-update feature \
  --project-dir /workspace \
  --feature-description "Add support for OAuth authentication"

# Using Gemini Files API
docker run --rm \
  -v /path/to/your/project:/workspace:ro \
  -v /path/to/output:/output \
  -e GEMINI_API_KEY="your_api_key_here" \
  -e GEMINI_UPDATE_USE_FILES="true" \
  gemini-update analyze --project-dir /workspace

Using Docker Compose

The repository includes a Docker Compose file for easier container management:

# Set environment variables
export GEMINI_API_KEY="your_api_key_here"
export PROJECT_DIR="/path/to/your/project" 
export OUTPUT_DIR="/path/to/output"

# Run the container with Docker Compose
docker-compose up

Using the Helper Script

A helper script is provided for convenience:

# Make the script executable
chmod +x gemini-update.sh

# Run the script
export GEMINI_API_KEY="your_api_key_here"
./gemini-update.sh analyze --project-dir /path/to/your/project

# Use Gemini Files API
export GEMINI_API_KEY="your_api_key_here"
./gemini-update.sh analyze --project-dir /path/to/your/project --use-gemini-files

Environment Variables

The following environment variables are supported:

Variable	Description	Default
GEMINI_API_KEY	Google Gemini API key	(Required)
GEMINI_MODEL	Gemini model to use	gemini-1.5-pro (defaults to gemini-1.5-pro internally, but gemini-2.5-pro is preferred if available)
GEMINI_UPDATE_OUTPUT_DIR	Directory to save output files	Current directory
GEMINI_UPDATE_USE_FILES	Enable Gemini Files API	false
GEMINI_UPDATE_MAX_FILE_SIZE	Maximum file size in MB for Gemini Files	4.0
GEMINI_UPDATE_MAX_FILES	Maximum number of files to analyze	100

How It Works

1. Codebase Analysis: The agent scans your project directory, identifies file types, analyzes imports and dependencies, and builds a structural model of your codebase. When GEMINI_UPDATE_USE_FILES is enabled, files are uploaded to the Gemini Files API, allowing the Gemini 2.5 Pro model to directly access and analyze the file contents as Blob objects, significantly improving context understanding for large codebases.

2. Feature Specification: Using natural language processing, the agent converts your feature description into a detailed specification with requirements, acceptance criteria, and technical notes.

3. Implementation Planning: Based on the codebase analysis and feature specification, the agent creates a detailed plan showing which files to modify or create, with specific code suggestions.

4. Output Generation: All results are saved as markdown files in the specified output directory.

Project Structure

gemini-update/
├── .venv/                      # Python virtual environment
├── src/
│   ├── agent/                  # Core agent logic and orchestration
│   │   ├── __init__.py
│   │   ├── agent.py            # Main GeminiUpdateAgent
│   │   ├── agents.py           # Specialized agents (Analyzer, Spec Generator, Planner)
│   │   ├── common.py           # Common Gemini API utilities
│   │   └── gemini_files.py     # Gemini Files API manager
│   ├── cli/                    # Command-line interface
│   │   └── main.py             # CLI entry point
│   ├── config.py               # Configuration utilities
│   ├── models/                 # Pydantic models for data structures
│   │   ├── __init__.py
│   │   ├── analysis.py         # Codebase analysis models (CodebaseContext, ImplementationPlan, etc.)
│   │   ├── code_execution.py   # Models for code execution results and requests
│   │   ├── completion_marker.py# Models for agent completion markers
│   │   ├── feature.py          # Feature specification models (FeatureSpec, Requirement, etc.)
│   │   ├── file_access.py      # Abstract file access layers
│   │   └── gemini.py           # Gemini agent configuration models
│   ├── prompts/                # Jinja2 templates for AI prompts
│   │   ├── __init__.py
│   │   ├── codebase_analyzer_prompt.py
│   │   ├── feature_spec_prompt.py
│   │   └── implementation_planner_prompt.py
│   ├── tools/                  # Pydantic-AI tools for agent interaction
│   │   ├── __init__.py
│   │   ├── codebase_tools.py   # Tools for codebase exploration (read_file, list_directory, etc.)
│   │   ├── code_execution_tools.py # Tools for dynamic code execution by Gemini
│   │   ├── documentation_tools.py  # Tools for searching documentation
│   │   └── feature_tools.py    # Tools for feature specification and planning
│   └── utils/                  # Utility functions
│       ├── __init__.py
│       └── code_executor.py    # Safe code execution in subprocesses
│       └── log.py              # Logging configuration
├── .env.example                # Example environment variables file
├── Dockerfile                  # Docker build file
├── gemini-update.py            # Main executable script
├── gemini-update.sh            # Helper script for Docker
├── pyproject.toml              # Project metadata and dependencies (if using Poetry/Rye)
├── requirements.txt            # Python dependencies
└── README.md                   # Project documentation

Core Components & Technologies

• Google Gemini API (google.generativeai): The backbone for all AI interactions, including content generation and the Files API.
• Pydantic (pydantic): Used extensively for defining structured data models (e.g., CodebaseContext, FeatureSpec, ImplementationPlan). This ensures robust data validation and clear communication between different parts of the system and the AI model.
• Pydantic-AI (pydantic_ai): Facilitates the creation of intelligent agents that can take structured inputs, use tools, and produce structured outputs, making the multi-step analysis and planning process manageable.
• Jinja2 (jinja2): Employed for templating prompts, allowing for dynamic and flexible instructions to the Gemini models based on the current context.
• Rich (rich): Provides a beautiful and informative command-line experience with rich text, progress bars, and logging.
• Pathlib (pathlib) & OS Module (os): For robust and cross-platform file system operations and path manipulation.
• Subprocess Module (subprocess): Used to safely execute dynamically generated Python code in isolated environments for codebase analysis.
• Python-Dotenv (python-dotenv): For loading environment variables from .env files, simplifying API key management.

API Interaction Details

The GeminiUpdateAgent is designed to be highly adaptive to the Gemini model capabilities. With your use of Gemini 2.5 Pro, the system can leverage its massive context window and advanced features, particularly through the GeminiFileManager and the --use-gemini-files flag.

When --use-gemini-files is enabled:

1. Files from your project_dir are intelligently selected and uploaded to the Gemini Files API. This creates Blob objects accessible by the Gemini model.
2. Instead of sending raw code snippets in the prompt, the agent provides references to these uploaded files (their URIs) to the Gemini model. This allows the model to "see" and understand the entire codebase (or a very large portion of it) at once, leading to more holistic and accurate analysis without hitting typical token limits in a single prompt.
3. The agent's tools (e.g., read_file, list_directory) are abstracted through FileAccessLayer (specifically GeminiFileAccessLayer), ensuring that operations transparently interact with the uploaded files or local copies as needed, providing a seamless experience for the AI.

This approach, Dave, directly addresses your goal of "just uploading files and prompting Gemini" by offloading the complex context management to the Gemini Files API and the large context window of Gemini 2.5 Pro.

License

MIT

Credits

This project builds on concepts from:

• Gemini Stack Trace
• Terraform Prompt Template
• Gemini Workspace