## Building a supypower script (for AI agents)

Your job: create a Python script that defines one or more *supypower* functions.

### 1) Add uv inline dependencies

At the very top of the file, include:

```text
# /// script
# dependencies = [
#   "pydantic",
# ]
# ///
```

This allows the script to run in isolation without a virtualenv.

### 2) Define a Pydantic input model

Each supypower function must accept exactly one parameter named `input`.
The type of `input` must be a Pydantic `BaseModel`.

### 3) (Optional) Define a Pydantic output model

Returning a Pydantic model is recommended because it produces clean JSON output.
You can return any type, but JSON-serializable types are best.

### 4) Write the function

Contract:
- The function has exactly **one** parameter named **`input`**
- `input` is annotated as a **Pydantic BaseModel**
- Add a clear docstring (used for documentation)

Example:

```python
def hello(input: HelloInput) -> HelloOutput:
    """Say hello."""
    return HelloOutput(greeting=f"Hello, {input.name}!")
```

### 5) Run it

From a folder that contains your script (e.g. `.`):

```bash
supypowers . run hello:hello "{'name': 'World'}"
```

### 6) Generate documentation

```bash
supypowers . docs --format json --output docs.json
supypowers . docs --format md --output docs.md
```
