🚀 aereo Plugin Template

Welcome to the aereo plugin template! This repository is your starting point for building high-performance, modular plugins for the aereo ecosystem.

Powered by the Polylith architecture and uv for lightning-fast dependency management, this template ensures your plugin is scalable, maintainable, and ready for production.

---

⚡ Quick Start

If you are new here, start with the setup script. It will bootstrap your environment, name your project, and create your first component automatically.

chmod +x setup.sh
./setup.sh

🔍 What does the setup script do?

The setup.sh script automates the tedious parts of starting a new Polylith plugin:

1. Validation: Ensures your project name follows the aereo- prefix rule.
2. Environment: Installs uv (if missing) and sets up the workspace dependencies.
3. Scaffolding: Creates your first Component (for code) and Project (for packaging).
4. Configuration: Generates a pre-configured pyproject.toml with standard entry points so aereo can immediately find your plugin.
5. Git Hooks: Installs prek to ensure high-quality commits from day one.

Important

The setup script is mandatory for new project initialization. It ensures consistent naming conventions (aereo- prefix) and registers your plugin entry points correctly.

---

🏗️ Architecture Overview

This project uses a Polylith structure. Instead of a messy monolith, code is organized into:

• Components: Pure logic and functionality (found in components/).
• Projects: Deployable artifacts like PyPI packages (found in projects/).
• Bases: Public APIs or entry points (CLI, FastAPI, etc.).

Why Polylith?

It allows you to share code between different projects within the same workspace perfectly, while keeping your deployments lean.

---

📖 Reference Plugins

If you want to see how production-ready plugins look in the wild, use these implementations as guides:

• Search Plugin Example: aereo-search-aws-goes
• Extraction Plugin Example: aereo-extract-aws-goes

---

🛠️ Development Workflow: Step-by-Step

Once you've run the setup script, here is a step-by-step guide to building your new plugin:

1. Identify Your Scaffolding

The setup.sh wizard automatically creates the initial file structure in components/aereo/your_component/. Inside, you will find a core.py that inherits from the correct base class:

• SearchProvider for projects starting with aereo-search-.
• Extractor for projects starting with aereo-extract-.

2. Implement Plugin Logic

Open components/aereo/your_component/core.py.

• For Search Providers: Override the search() method to return a GeoDataFrame matching the AssetSchema.
• For Extractors: Override prepare_for_extraction() and extract() to handle processing workflows and return an ArtifactSchema GeoDataFrame.
  • prepare_for_extraction() receives a GridConfig object — read tiling parameters (cell size, margin, overlap) from it rather than hard-coding defaults.
  • Domain config lives on profile.extract_params; the old prepare_params catch-all has been removed. (Hint: Peek into the Reference Plugins to see exact implementations!)

3. Check Workspace Info

See the state of your workspace, which components are used by which projects:

uv run poly info

4. Adding Dependencies

Use uv to manage your environment. For example:

uv add requests          # Add to the workspace
uv add --group dev pytest  # Add development tools

5. Running Tests

Tests are enabled globally. Write your tests inside components/aereo/your_component/test/ and run them with:

uv run pytest

---

📦 Creating More Components (Advanced)

If your plugin grows and you need to split logic into more components, you can use the Polylith CLI:

# Create a new component
uv run poly create component --name my_new_feature

# Create a new project (if you want to ship a separate package)
uv run poly create project --name aereo-my-other-package

---

🚀 Releasing Plugins

Releases are automated using Conventional Commits and python-semantic-release.

1. Commit with prefixes: Use feat:, fix:, or chore: in your commit messages.
2. Run the release script:

   # Release a specific project
   python3 .agents/scripts/release.py aereo-my-plugin
   
   # Release all changed projects
   python3 .agents/scripts/release.py --changed

🤖 Agentic Workflow

If you are working with Antigravity or another AI assistant, you can simply say:

"Release my plugin" or "Create a new release for aereo-search-earthaccess"

The assistant will use the new-release skill to handle the versioning, tagging, and pushing for you.

---

📜 License

This template is licensed under the Apache License 2.0.