Git Commit Agent

Agente de IA en línea de comandos que inspecciona los cambios de un repositorio Git y propone un mensaje compatible con Conventional Commits.

El proyecto demuestra un flujo básico de agentic AI: un Large Language Model (LLM) decide qué herramientas necesita ejecutar, analiza la evidencia obtenida y repite el ciclo hasta generar una respuesta final estructurada. El agente opera en modo read-only; puede consultar el estado, los diffs y el historial del repositorio, pero no modifica archivos ni crea commits.

Funcionalidades

• Agent loop con un máximo de iteraciones configurable.
• Tool calling mediante una API compatible con OpenAI.
• Análisis de cambios staged y unstaged.
• Consulta opcional de commits recientes para identificar convenciones del repositorio.
• Respuesta con commit message, resumen, nivel de confianza y notas.
• Soporte para un LLM alojado en Groq o ejecutado localmente con Ollama.
• Validación de herramientas permitidas, timeouts y truncamiento de outputs extensos.

Arquitectura

flowchart LR
    CLI["CLI · agent.py"] --> LLM["LLM · Groq / Ollama"]
    LLM -->|"tool call"| Dispatcher["Tool dispatcher"]
    Dispatcher --> Tools["Read-only Git tools"]
    Tools -->|"status · diff · log"| Repository["Git repository"]
    Tools -->|"tool result"| LLM
    LLM -->|"final answer"| CLI

Loading

El LLM no ejecuta comandos arbitrarios. agent.py expone un conjunto cerrado de funciones y git_tools.py limita la interacción a operaciones de lectura.

Stack

• Python 3.14+
• OpenAI Python SDK
• python-dotenv
• Groq u Ollama como LLM provider
• uv para gestión del entorno y dependencias
• Git

Estructura del proyecto

Archivo	Responsabilidad
agent.py	Define el system prompt, las tools y el agent loop.
git_tools.py	Implementa las operaciones read-only sobre Git.
llm.py	Configura el client y el model según el provider.
hello_llm.py	Contiene un ejemplo mínimo de llamada a Groq.
.env.template	Documenta las variables de entorno requeridas.
pyproject.toml	Declara la versión de Python y las dependencias.

Requisitos

• Git.
• uv.
• Una de estas opciones:
  • Una API key de Groq.
  • Una instalación local de Ollama y un model con soporte para tool calling.

Instalación

Clona el repositorio, entra al directorio del proyecto e instala las dependencias:

git clone <URL_DEL_REPOSITORIO>
cd agentic-example
uv sync

Crea el archivo de configuración local:

cp .env.template .env

Para utilizar Groq, reemplaza el valor de GROQ_API_KEY en .env:

GROQ_BASE_URL=https://api.groq.com/openai/v1
GROQ_API_KEY=tu-api-key
GROQ_MODEL=llama-3.3-70b-versatile

Para utilizar Ollama, inicia el servicio y descarga el model configurado:

ollama serve
ollama pull llama3.2:1b

La configuración correspondiente en .env es:

OLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_MODEL=llama3.2:1b

.env está excluido de Git y no debe contener credenciales que puedan publicarse.

Uso

Ejecuta el agente sobre el repositorio actual con Groq:

uv run python agent.py --provider groq --repo .

O utiliza Ollama como provider local:

uv run python agent.py --provider ollama --repo .

El argumento --repo acepta la ruta de cualquier repositorio Git. Groq es el provider predeterminado y el límite por defecto es de seis iteraciones:

uv run python agent.py \
  --provider groq \
  --repo /ruta/al/repositorio \
  --max-iterations 6

El agente prioriza los cambios staged. Si únicamente existen archivos untracked, deben agregarse al staging area para que su contenido aparezca en el diff:

git add <archivo>
uv run python agent.py --provider groq --repo .

La respuesta mantiene el siguiente contrato:

COMMIT_MESSAGE:
<type>(<optional-scope>): <description>

SUMMARY:
- <cambio identificado>

CONFIDENCE:
<high, medium, or low>

NOTES:
<limitación relevante o None>

Pruebas

Actualmente el proyecto no incluye una test suite automatizada. Se pueden ejecutar los siguientes smoke tests locales:

# Validar sintaxis
uv run python -m py_compile agent.py git_tools.py llm.py hello_llm.py

# Validar la interfaz CLI
uv run python agent.py --help

Para una prueba end-to-end:

1. Crea o modifica un archivo en un repositorio Git.
2. Ejecuta git add <archivo> para incluirlo en el staging area.
3. Inicia el agente con el provider configurado.
4. Verifica que la respuesta describa únicamente los cambios presentes y que el commit message siga Conventional Commits.

El ejemplo mínimo de conexión a Groq puede probarse de forma independiente con:

uv run python hello_llm.py

Estado del proyecto

Este repositorio es un proyecto educativo y se encuentra en desarrollo. Su objetivo actual es explorar patrones fundamentales de agentic AI —tool calling, agent loops, grounding y guardrails— aplicados a un caso de uso concreto para developer tooling.