🕺 Groovy

Hello! This is groovy, a Python library that makes it easy to build, debug, and share workflows (flows), e.g. autonomous applications that perform actions using your browser or desktop.

✨ Build flows with a simple high-level Flow class that can wrap any kind of application. Since groovy comes "batteries-included", you can write your first Flow to control a browser in just a single line.

🔎 Debug flows with an intuitive Gradio user interface, that exposes agent thought while it runs and allows users to "step-in" and intervene at any point.

🤗 Share flows on Hugging Face Spaces publicly (or with specific collaborators) and reuse flows from the community

Installation

$ pip install groovy[full]

Key Features

1. Get started immediately ✨

Run browser automations with a single terminal command. No need for complex setup or boilerplate code:

$ groovy flow "Use Wikipedia to tell me the birth date of George Washington. Return the final answer in this format: MM-DD-YYYY."

Note: by default, Groovy uses a web-browsing agent built using the excellent smolagents library. The web-browsing agent works best when provided detailed, step-by-step instructions.

2. Customize Flows

Create interactive automation apps using the Flow class. You can define input parameters that users can customize before running the flow:

from groovy import Flow
import gradio as gr

flow = Flow(
    task="Find the next upcoming meetup in {} related to {}",
    inputs=[
        gr.Textbox(label="Location", value="San Francisco")
        gr.Textbox(label="Activity", value="board games"),
    ]
)

flow.launch()

Run Flows Programmatically

The Flow class can also be run programmatically so that it can be used as part of larger programs. Here's an example:

from groovy import Flow
import csv

flow = Flow(task="Find the next upcoming meetup in {} related to {}")

cities = [
    "San Francisco", "New York", "Chicago", "Los Angeles", "Seattle",
    "Austin", "Boston", "Denver", "Portland", "Miami"
]

results = []
for city in cities:
    event_info = flow.run(city, "board games")
    results.append({"city": city, "event": event_info})

with open("board_game_events.csv", "w", newline="") as f:
    writer = csv.DictWriter(f, fieldnames=["city", "event"])
    writer.writeheader()
    writer.writerows(results)

3. Easy Sharing via Hugging Face Spaces

Share your automation workflows with others by publishing to Hugging Face Spaces. Just navigate to your project folder and run:

$ groovy publish

This will create a public (you can change visibility to private) Hugging Face Space where others can access and use your automation.

4. Use Community Workflows

Take advantage of existing workflows created by the community. Run any published workflow locally, e.g.:

$ groovy flow https://huggingface.co/spaces/abidlabs/Activity_Finder

The Python equivalent to load a Flow from Spaces is:

import groovy as gv

flow = gv.Flow.from_space("https://huggingface.co/spaces/abidlabs/Activity_Finder")

Roadmap aka leftover TODOs

• Support structured generation in .run() -- how would this work?
• Support max_steps / max_time in .run()
• Make it easier to modify the default agent
• Allow task to be an arbitrary function of inputs, not just a format string
• Add Flow.run(**input) which runs the flow programmatically without the Gradio UI
• Add support for browser-use and desktop apps
• Make screen recording more robust
• Generally improve troubleshooting
• Add support for using the user's default browser
• Add better examples in readme / Spaces (twitter explorer find tweets about a particular topic), research presidents' wife. Chain Flows together
• Autogenerated docs
• Better cleanup of gradio ui and browsing windows when script is terminated
• Allow pausing / stopping from gradio ui
• Improve default BrowserAgent tool as it gives lookup errors way too often.
• Warn before using OPENAI_API_KEY / HF_TOKEN

Contributing

Contributions are welcome! Feel free to submit bug reports and feature requests or submit pull requests. Star this repo if you find it interesting ⭐