API Contract Agent

The API Contract Agent is a CLI tool that leverages a Large Language Model (LLM) powered by Google's Gemini to automatically generate OpenAPI 3.0 specifications based on user-defined profiles and ticket requirements. This helps bridge the gap in API development by ensuring teams are aligned on API contracts before implementation, reducing delays and misalignments.

Features

• Profile-Based Generation: Choose from three profiles:
  • poc: Fast Proof of Concept - Quick and dirty contracts for prototyping.
  • internal: Internal API Integrations - Structured contracts for internal systems.
  • external: External Client-Facing - Comprehensive, secure contracts for public APIs.
• LLM-Powered: Uses Gemini AI to interpret requirements and generate compliant OpenAPI YAML.
• CLI Interface: Simple command-line interface for easy integration into workflows.
• Customizable Rules: References a rules.md file for generation guidelines.

Prerequisites

• Python 3.8+
• Google Gemini API key
• Required packages: Install via pip install -r requirement.txt

Setup

1. Clone or navigate to the repository.

2. Create a .env file in the root directory and add your Gemini API key:

   API_KEY=your_gemini_api_key_here
   

3. Install dependencies:

   pip install -r requirement.txt

Usage

Run the agent from the command line with the following syntax:

python src/agent.py --profile <profile> --ticket <ticket_file> [--output <output_file>]

Arguments

• --profile: Required. Choose poc, internal, or external.
• --ticket: Required. Path to a text file containing the ticket requirements.
• --output: Optional. Path to save the generated OpenAPI YAML. If omitted, outputs to stdout.
• --list-models: Optional. List available Gemini models and exit.

Sample Command

python src/agent.py --profile poc --ticket ticket.txt --output contract.yaml

This generates a POC-level OpenAPI contract from ticket.txt and saves it to contract.yaml.

Viewing the Contract

Open the generated contract.yaml in Swagger UI (e.g., https://editor.swagger.io/) to visualize and test the API contract.

© 2025 API Contract Generation Agent. All rights reserved.