rainfall-cli 0.2.0

Call functions that don't exist. Let AI figure it out.

🌧️ Rainfall

Call functions that don't exist. AI writes and executes the code.

Rainfall is a Python CLI that runs your scripts with AI-powered stub functions. Write the function signature and docstring, leave the body as ..., and Rainfall generates real working code.

Installation

pip install rainfall-cli

Quick Start

1. Set your Gemini API key:

export GEMINI_API_KEY=your_api_key_here

Get a free key at Google AI Studio.

2. Write a script with stub functions:

# my_script.py

def calculate_tip(bill: float, quality: str) -> float:
    """
    Calculate tip based on bill and service quality.
    Quality: 'poor', 'okay', 'good', 'excellent'
    """
    ...


def fetch_page_title(url: str) -> str:
    """Fetch a webpage and extract its <title> tag."""
    ...


def count_image_pixels(path: str) -> int:
    """Count total pixels in an image file."""
    ...


# Use them like normal functions
print(f"Tip: ${calculate_tip(85.50, 'excellent')}")
print(f"Title: {fetch_page_title('https://python.org')}")
print(f"Pixels: {count_image_pixels('photo.jpg')}")

3. Run with Rainfall:

rainfall my_script.py

Rainfall generates real Python code for each stub and executes it.

How It Works

1. Parse — Finds stub functions (body is ..., pass, or NotImplementedError)
2. Generate — Asks LLM to write the function implementation
3. Cache — Stores generated code (same function = same code)
4. Execute — Runs the generated code with your arguments

def fetch_page_title(url: str) -> str:
    """Fetch a webpage and extract its <title> tag."""
    ...

# Rainfall generates:
response = requests.get(url)
match = re.search(r'<title>(.*?)</title>', response.text)
return match.group(1) if match else ""

What It Can Do

Because Rainfall executes real code, it can:

• ✅ Make HTTP requests (requests pre-imported)
• ✅ Process images (PIL.Image pre-imported)
• ✅ Read/write files (pathlib, os pre-imported)
• ✅ Parse JSON, regex, math operations
• ✅ Any pure Python computation

CLI Options

rainfall script.py                    # Run with defaults
rainfall script.py --verbose          # Show generated code
rainfall script.py --dry-run          # List stubs without running
rainfall script.py --model MODEL      # Use different model

Best Practices

Write Clear Docstrings

The docstring is your prompt. Be specific:

# ✅ Good - AI knows exactly what to do
def extract_emails(text: str) -> list:
    """
    Extract all email addresses from text.
    Returns a list of email strings.
    """
    ...

# ❌ Vague - AI has to guess
def process(data):
    """Process the data."""
    ...

Use Type Hints

def get_count() -> int: ...      # AI returns an integer
def get_names() -> list: ...     # AI returns a list
def is_valid() -> bool: ...      # AI returns True/False

Pre-imported Modules

Generated code has access to:

• os, sys, json, re, math, datetime, html
• pathlib.Path
• requests (HTTP)
• PIL.Image (images)

License

MIT