core: add flexible_api decorator to fix mypy override errors

[andreahlert]

Summary

• Adds a flexible_api decorator that can be applied to run, stream_run, or run_and_update overrides using explicit parameters instead of **run_kwargs
• Prevents mypy [override] errors caused by narrowing the base-class signature
• Exported from burr.core for easy access

Context

When users define class-based actions with typed parameters in run() (which is the documented pattern), mypy reports an [override] error because the subclass signature is incompatible with Function.run(self, state, **run_kwargs).

The decorator wraps the method so mypy sees Callable[..., Any], which is compatible with the base signature.

Before (triggers mypy error)

class Counter(Action):
    def run(self, state: State, increment_by: int) -> dict:  # mypy: [override]
        return {"counter": state["counter"] + increment_by}

After (no mypy error)

from burr.core import flexible_api

class Counter(Action):
    @flexible_api
    def run(self, state: State, increment_by: int) -> dict:  # ok
        return {"counter": state["counter"] + increment_by}

Test plan

• Tested in isolated Docker environment (Python 3.12, mypy 1.19.1) confirming the decorator eliminates the [override] error
• Class without decorator still triggers the error as expected (no behavior change for existing code)

Closes #457

[skrawcz]

Let's not do this. It doesn't make the project better. Instead let's think about a better typed approach that would make mypy happy.

[skrawcz]

let's rethink the approach.

[skrawcz]

Okay @andreahlert after digging in a bit more. Let's name the decorator @type_eraser or something -- since that will be clearer what the purpose is.

[andreahlert]

Okay @andreahlert after digging in a bit more. Let's name the decorator @type_eraser or something -- since that will be clearer what the purpose is.

Nice. Renamed to @type_eraser as suggested and found and fixed an extra bug where the original @wraps wrapper was breaking is_async() detection for async and generator functions.

Added some extra tests covering sync and etc.

Ready to review